Checkout Sessions

A Checkout Session represents your customer's session as they are making a payment. It is the primary mechanism for collecting payment details to create a one-time payment or a subscription. After you create a Session, you redirect the customer to a secure, hosted payment page. Once the payment is complete, the customer is redirected back to your application.

Related guides: One-Time Payments, Subscriptions.

The Checkout Session Object#

A Checkout Session object contains all the details about the payment flow, including line items, payment status, and customer information.

Attribute	Type	Description
id	string	Unique identifier for the object.
url	string	The URL to which you should redirect your customer to complete the payment.
status	string	The status of the Checkout Session. Can be open, complete, or expired.
payment_status	string	The payment status of the session. Can be paid, unpaid, or no_payment_required.
mode	string	The mode of the Checkout Session, which determines the type of payment being collected. Can be payment, setup, or subscription.
amount_subtotal	string	Total of all line item prices.
amount_total	string	The total amount after discounts and taxes are applied.
currency_id	string	The ID of the currency used for the payment.
customer_id	string	The ID of the Customer for this session.
line_items	array	A list of items the customer is purchasing.
metadata	object	A set of key-value pairs that you can attach to an object.
success_url	string	The URL to redirect to on successful payment.
cancel_url	string	The URL to redirect to if the customer cancels the session.
expires_at	number	The Unix timestamp at which the Checkout Session will expire.

Create a Checkout Session#

Creates a Session for a customer to enter their payment details.

const session = await payment.checkoutSessions.create({
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price_id: 'price_12345',
      quantity: 1,
    },
  ],
  mode: 'payment', // or 'subscription'
});

Parameters

Name	Type	Description
line_items	array	Required. A list of line item objects. See the Line Item Properties table below for details.
success_url	string	Required. The URL to which the customer will be directed after a successful payment.
cancel_url	string	Required. The URL to which the customer will be directed if they cancel the payment.
allow_promotion_codes	boolean	Enables the use of promotion codes. Defaults to false.
billing_address_collection	string	Specifies whether to collect the customer's billing address. Can be auto or required. Defaults to auto.
client_reference_id	string	A unique string to reference the Checkout Session. This can be used to reconcile the session with your internal systems.
customer_id	string	The ID of an existing Customer to associate with this session.
customer_creation	string	Determines how to handle customer creation. Can be if_required or always. Defaults to always.
expires_at	number	A Unix timestamp after which the session will expire. Defaults to 24 hours from creation.
metadata	object	A set of key-value pairs to store additional information about the object.
payment_intent_data	object	Data that will be used to create the underlying PaymentIntent. See the Payment Intent Data Properties table below.
subscription_data	object	Data that will be used to create a subscription if the session is in subscription mode. See the Subscription Data Properties table below.
include_free_trial	boolean	If true and the session is in subscription mode, it will include any trial period defined on the price.

Line Item Properties

Name	Type	Description
price_id	string	The ID of the Price object.
quantity	number	The quantity of the line item being purchased. Defaults to 1.
adjustable_quantity	object	Allows the customer to adjust the quantity of this line item on the checkout page. Contains enabled (boolean), minimum (number), and maximum (number) properties.

Subscription Data Properties

Name	Type	Description
description	string	An optional description for the subscription.
trial_period_days	number	The number of trial days for the subscription.
metadata	object	A set of key-value pairs to store on the subscription.

Returns

The created Checkout Session object.

{
  "id": "cs_123456789",
  "object": "checkout.session",
  "url": "https://checkout.example.com/pay/cs_123456789",
  "status": "open",
  "payment_status": "unpaid",
  "mode": "payment",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "line_items": [
    {
      "price_id": "price_12345",
      "quantity": 1
    }
  ],
  "expires_at": 1678886400,
  // ... other properties
}

Retrieve a Checkout Session#

Retrieves the details of an existing Checkout Session.

const session = await payment.checkoutSessions.retrieve('cs_123456789');

Parameters

Name	Type	Description
id	string	Required. The unique identifier of the Checkout Session to retrieve.

Returns

The retrieved Checkout Session object.

{
  "id": "cs_123456789",
  "object": "checkout.session",
  "status": "complete",
  "payment_status": "paid",
  // ... other properties
}

Update a Checkout Session#

Updates a Checkout Session object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

const session = await payment.checkoutSessions.update('cs_123456789', {
  metadata: {
    order_id: '6735'
  }
});

Parameters

Name	Type	Description
id	string	Required. The ID of the session to update.
metadata	object	A set of key-value pairs to store on the object. This is the only field that can be updated.

Returns

The updated Checkout Session object.

List all Checkout Sessions#

Returns a list of your Checkout Sessions. The sessions are returned sorted by creation date, with the most recent sessions appearing first.

const sessions = await payment.checkoutSessions.list({
  limit: 5,
  status: 'open'
});

Parameters

Name	Type	Description
status	string	Filter sessions by status. Can be open, complete, or expired.
payment_status	string	Filter sessions by payment status. Can be paid, unpaid, or no_payment_required.
customer_id	string	Only return sessions for the given customer ID.
customer_did	string	Only return sessions for the given customer DID.
payment_intent_id	string	Only return the session for the given PaymentIntent.
payment_link_id	string	Only return sessions created from the given Payment Link.
subscription_id	string	Only return the session for the given subscription.
metadata.{key}	string	Filter by custom metadata fields. For example, metadata.order_id: '6735'.
page	number	The page number for pagination. Defaults to 1.
pageSize	number	The number of items per page. Defaults to 20.

Returns

A paginated object containing a list of Checkout Session objects.

{
  "count": 15,
  "list": [
    {
      "id": "cs_123456789",
      "object": "checkout.session",
      "status": "open",
      // ... other properties
    },
    {
      "id": "cs_987654321",
      "object": "checkout.session",
      "status": "open",
      // ... other properties
    }
  ]
}

Expire a Checkout Session#

Manually expires a Checkout Session. This action is irreversible.

const session = await payment.checkoutSessions.expire('cs_123456789');

Parameters

Name	Type	Description
id	string	Required. The ID of the Checkout Session to expire.

Returns

The expired Checkout Session object with a status of expired.

{
  "id": "cs_123456789",
  "object": "checkout.session",
  "status": "expired",
  // ... other properties
}