API Reference

Checkout Sessions

A Checkout Session represents a customer's payment session. It is a foundational object for creating one-time payments and subscriptions. When a customer initiates a payment process, you create a Checkout Session to define the line items, payment mode, and other configurations. The SDK then provides a URL to redirect the customer to a secure, hosted payment page.
The Checkout Session Object#A Checkout Session object contains all the details for a single payment flow, including line items, payment status, customer details, and success/cancel URLs.
Properties#Property
Type
Description
id
string
Unique identifier for the Checkout Session.
status
string
The status of the 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, determined by the line items. Can be payment, setup, or subscription.
url
string
The URL to the hosted checkout page for this session. Redirect your customer to this URL to complete the payment.
line_items
array
A list of items the customer is purchasing.
amount_total
string
The total amount for the session in the smallest currency unit (e.g., cents).
currency_id
string
The ID of the currency for the payment.
customer_id
string
The ID of the Customer for this session.
metadata
object
A set of key-value pairs that you can attach to an object.
success_url
string
The URL to which the customer will be redirected after a successful payment.
cancel_url
string
The URL to which the customer will be redirected if they cancel the payment.
Create a Session#Creates a Checkout Session object.
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,
    },
  ],
});Parameters#Parameter
Type
Description
line_items
array
Required. A list of line item objects. See the Line Item Object Properties table below.
success_url
string
Required. The URL to redirect to after a successful payment.
cancel_url
string
Required. The URL to redirect to if the customer cancels the session.
allow_promotion_codes
boolean
Enables promo code redemption. Default is false.
billing_address_collection
string
Specifies whether to collect the customer's billing address. Can be auto or required. Default is auto.
client_reference_id
string
A unique string to reference the Checkout Session.
currency_id
string
The currency for the session. If not provided, it's inferred from the first line item's price.
customer_creation
string
Determines when to create a Customer object. Can be if_required or always. Default is always.
enable_subscription_grouping
boolean
Groups multiple subscriptions into a single checkout flow. Default is false.
expires_at
number
The Unix timestamp at which the Checkout Session will expire. Default is 30 minutes from creation.
include_free_trial
boolean
If true and the session is for a subscription with a trial period, the trial will be included.
metadata
object
Key-value data to attach to the session.
submit_type
string
The text on the submit button. Can be pay, book, donate, or auto. Default is pay.
subscription_data
object
Data to be used when creating a subscription. See the Subscription Data Object Properties table below.
Line Item Object Properties
Property
Type
Description
price_id
string
Required. The ID of the Price object.
quantity
number
Required. The quantity of the line item.
adjustable_quantity
object
Allows the customer to adjust the quantity on the checkout page. Contains enabled (boolean), minimum (number), and maximum (number) properties.
custom_amount
string
A custom amount for the line item, used for prices with custom_unit_amount enabled.
Subscription Data Object Properties
Property
Type
Description
trial_period_days
number
Number of trial days for a new subscription.
trial_end
number
Unix timestamp indicating the end of the trial period.
billing_threshold_amount
number
A threshold for the billing amount that triggers an invoice.
min_stake_amount
number
The minimum stake amount required for the subscription.
no_stake
boolean
If true, the subscription does not require staking.
description
string
An optional description for the subscription.
service_actions
array
An array of service action objects to display to the customer. Each object can define name, text, link, etc.
Returns#Returns a Checkout Session object if the call succeeded.
{
  "id": "cs_123456789",
  "status": "open",
  "payment_status": "unpaid",
  "mode": "payment",
  "url": "https://checkout.example.com/pay/cs_123456789",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "line_items": [
    {
      "price_id": "price_12345",
      "quantity": 1
    }
  ],
  "amount_total": "1000",
  "currency_id": "usd",
  "customer_id": null,
  "metadata": {},
  "created_at": 1678886400,
  "expires_at": 1678888200
}Retrieve a Session#Retrieves a Checkout Session object by its ID.
const sessionId = 'cs_123456789';
const session = await payment.checkoutSessions.retrieve(sessionId);Parameters#Parameter
Type
Description
id
string
Required. The unique identifier of the Checkout Session to retrieve.
Returns#Returns the Checkout Session object, including expanded details for line_items.
{
  "id": "cs_123456789",
  "status": "complete",
  "payment_status": "paid",
  "mode": "payment",
  "line_items": [
    {
      "price_id": "price_12345",
      "quantity": 1,
      "price": {
        "id": "price_12345",
        "active": true,
        "unit_amount": "1000",
        "currency_id": "usd",
        "type": "one_time"
      }
    }
  ],
  "amount_total": "1000",
  "currency_id": "usd",
  "customer_id": "cus_abcdefg",
  "payment_intent_id": "pi_hijklmn"
}Update a Session#Updates a Checkout Session object. Currently, only the metadata can be updated.
const sessionId = 'cs_123456789';
const updatedSession = await payment.checkoutSessions.update(sessionId, {
  metadata: {
    order_id: '6735'
  }
});Parameters#Parameter
Type
Description
id
string
Required. The ID of the Checkout Session to update.
metadata
object
Required. A set of key-value pairs to store on the object.
Returns#Returns the updated Checkout Session object.
{
  "id": "cs_123456789",
  "status": "open",
  "metadata": {
    "order_id": "6735"
  }
}List all Sessions#Returns a paginated list of Checkout Sessions.
const sessions = await payment.checkoutSessions.list({
  pageSize: 5,
  payment_status: 'paid'
});Parameters#Parameter
Type
Description
status
string
Filter sessions by status (open, complete, expired).
payment_status
string
Filter sessions by payment status (paid, unpaid).
nft_mint_status
string
Filter sessions by NFT mint status (pending, succeeded, failed).
customer_id
string
Filter sessions for a specific customer ID.
customer_did
string
Filter sessions for a specific customer DID.
payment_intent_id
string
Filter sessions associated with a specific Payment Intent.
payment_link_id
string
Filter sessions created from a specific Payment Link.
subscription_id
string
Filter sessions associated with a specific Subscription.
metadata.{key}
string
Filter by custom metadata fields.
page
number
The page number for pagination. Default is 1.
pageSize
number
The number of items per page. Default is 20.
Returns#Returns an object containing a list of Checkout Session objects and pagination details.
{
  "count": 15,
  "list": [
    {
      "id": "cs_123456789",
      "status": "complete",
      "payment_status": "paid"
    },
    {
      "id": "cs_987654321",
      "status": "complete",
      "payment_status": "paid"
    }
  ]
}Expire a Session#Expires an open Checkout Session. Once expired, it can no longer be used to complete a payment.
const sessionId = 'cs_123456789';
const expiredSession = await payment.checkoutSessions.expire(sessionId);Parameters#Parameter
Type
Description
id
string
Required. The ID of the Checkout Session to expire.
Returns#Returns the expired Checkout Session object with its status changed to expired.
{
  "id": "cs_123456789",
  "status": "expired",
  "payment_status": "unpaid"
}

Property	Type	Description
`id`	`string`	Unique identifier for the Checkout Session.
`status`	`string`	The status of the 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, determined by the line items. Can be `payment`, `setup`, or `subscription`.
`url`	`string`	The URL to the hosted checkout page for this session. Redirect your customer to this URL to complete the payment.
`line_items`	`array`	A list of items the customer is purchasing.
`amount_total`	`string`	The total amount for the session in the smallest currency unit (e.g., cents).
`currency_id`	`string`	The ID of the currency for the payment.
`customer_id`	`string`	The ID of the Customer for this session.
`metadata`	`object`	A set of key-value pairs that you can attach to an object.
`success_url`	`string`	The URL to which the customer will be redirected after a successful payment.
`cancel_url`	`string`	The URL to which the customer will be redirected if they cancel the payment.

Parameter	Type	Description
`line_items`	`array`	Required. A list of line item objects. See the Line Item Object Properties table below.
`success_url`	`string`	Required. The URL to redirect to after a successful payment.
`cancel_url`	`string`	Required. The URL to redirect to if the customer cancels the session.
`allow_promotion_codes`	`boolean`	Enables promo code redemption. Default is `false`.
`billing_address_collection`	`string`	Specifies whether to collect the customer's billing address. Can be `auto` or `required`. Default is `auto`.
`client_reference_id`	`string`	A unique string to reference the Checkout Session.
`currency_id`	`string`	The currency for the session. If not provided, it's inferred from the first line item's price.
`customer_creation`	`string`	Determines when to create a Customer object. Can be `if_required` or `always`. Default is `always`.
`enable_subscription_grouping`	`boolean`	Groups multiple subscriptions into a single checkout flow. Default is `false`.
`expires_at`	`number`	The Unix timestamp at which the Checkout Session will expire. Default is 30 minutes from creation.
`include_free_trial`	`boolean`	If `true` and the session is for a subscription with a trial period, the trial will be included.
`metadata`	`object`	Key-value data to attach to the session.
`submit_type`	`string`	The text on the submit button. Can be `pay`, `book`, `donate`, or `auto`. Default is `pay`.
`subscription_data`	`object`	Data to be used when creating a subscription. See the Subscription Data Object Properties table below.

Property	Type	Description
`price_id`	`string`	Required. The ID of the Price object.
`quantity`	`number`	Required. The quantity of the line item.
`adjustable_quantity`	`object`	Allows the customer to adjust the quantity on the checkout page. Contains `enabled` (boolean), `minimum` (number), and `maximum` (number) properties.
`custom_amount`	`string`	A custom amount for the line item, used for prices with `custom_unit_amount` enabled.

Property	Type	Description
`trial_period_days`	`number`	Number of trial days for a new subscription.
`trial_end`	`number`	Unix timestamp indicating the end of the trial period.
`billing_threshold_amount`	`number`	A threshold for the billing amount that triggers an invoice.
`min_stake_amount`	`number`	The minimum stake amount required for the subscription.
`no_stake`	`boolean`	If `true`, the subscription does not require staking.
`description`	`string`	An optional description for the subscription.
`service_actions`	`array`	An array of service action objects to display to the customer. Each object can define `name`, `text`, `link`, etc.

Parameter	Type	Description
`id`	`string`	Required. The ID of the Checkout Session to update.
`metadata`	`object`	Required. A set of key-value pairs to store on the object.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Checkout Sessions

The Checkout Session Object#

Properties#

Create a Session#

Parameters#

Returns#

Retrieve a Session#

Parameters#

Returns#

Update a Session#

Parameters#

Returns#

List all Sessions#

Parameters#

Returns#

Expire a Session#

Parameters#

Returns#

API Reference

Customers

Parameter	Type	Description
`status`	`string`	Filter sessions by status (`open`, `complete`, `expired`).
`payment_status`	`string`	Filter sessions by payment status (`paid`, `unpaid`).
`nft_mint_status`	`string`	Filter sessions by NFT mint status (`pending`, `succeeded`, `failed`).
`customer_id`	`string`	Filter sessions for a specific customer ID.
`customer_did`	`string`	Filter sessions for a specific customer DID.
`payment_intent_id`	`string`	Filter sessions associated with a specific Payment Intent.
`payment_link_id`	`string`	Filter sessions created from a specific Payment Link.
`subscription_id`	`string`	Filter sessions associated with a specific Subscription.
`metadata.{key}`	`string`	Filter by custom metadata fields.
`page`	`number`	The page number for pagination. Default is `1`.
`pageSize`	`number`	The number of items per page. Default is `20`.