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.

Create a Checkout Session

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.

Response

{
  "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.

Retrieve a 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.

Response

{
  "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.

Update a Checkout Session

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.

List Checkout Sessions

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.

Response

{
  "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.

Expire a Checkout Session

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.

Response

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