API Reference

Checkout Sessions

A Checkout Session orchestrates the payment flow for one-time payments or subscriptions. When a customer is ready to pay, you create a Session and redirect them to its unique URL. This guide covers the API for managing Checkout Sessions.
For practical examples and implementation walkthroughs, please refer to our Usage Guide for Checkout Sessions.
The Checkout Session Object#A Checkout Session object contains all the details about a single purchase flow.
Attribute
Type
Description
id
string
Unique identifier for the Checkout Session.
url
string
The URL to which you should redirect your customer to complete the payment. This is available only after creation.
status
string
The current status of the session. Can be 'open', 'complete', or 'expired'.
payment_status
string
The payment status for the session. Can be 'paid', 'unpaid', or 'no_payment_required'.
mode
string
The mode of the Checkout Session, determining its purpose. Can be 'payment', 'setup', or 'subscription'.
customer_id
string
The ID of the associated Customer, if one exists.
subscription_id
string
The ID of the subscription created if the session is in subscription mode.
line_items
Array<Object>
A list of items the customer is purchasing.
success_url
string
The URL to redirect to after a successful payment.
cancel_url
string
The URL to redirect to if the customer cancels the payment flow.
expires_at
number
The Unix timestamp at which the session will expire.
metadata
Object
A set of key-value pairs that you can attach to the object for your own reference.
Create a Checkout Session#Creates a new session to initiate a payment or subscription flow.
Parameters
Name
Type
Description
mode
string
The mode of the Checkout Session. Required. Can be 'payment', 'setup', or 'subscription'.
line_items
Array<Object>
A list of line items for the session. Each item object must contain a price_id and quantity. Required.
success_url
string
The URL the customer will be directed to after a successful purchase. Required.
cancel_url
string
The URL the customer will be directed to if they cancel the purchase. Required.
customer_id
string
ID of an existing customer to associate with this session. Optional.
payment_method_types
Array<string>
A list of payment method types to accept (e.g., 'stripe', 'arcblock'). Optional.
allow_promotion_codes
boolean
Enables user-redeemable promotion codes. Optional.
subscription_data
Object
Data used when mode is 'subscription', such as trial_period_days. Optional.
metadata
Object
Key-value data to store with the session. Optional.
Returns
Returns the newly created TCheckoutSession object. The url attribute contains the redirect link for the customer.
Example
async function createCheckoutSession() {
  try {
    const session = await payment.checkoutSessions.create({
      success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: 'https://example.com/cancel',
      line_items: [{
        price_id: 'price_123456789',
        quantity: 2,
      }],
      mode: 'payment',
      metadata: {
        order_id: 'order_abc123'
      }
    });
    console.log('Redirect your customer to:', session.url);
  } catch (error) {
    console.error('Error creating session:', error);
  }
}

createCheckoutSession();Example Response
{
  "id": "cs_xxxxxxxxxxxxxx",
  "object": "checkout.session",
  "url": "https://pay.arcblock.io/session/cs_xxxxxxxxxxxxxx",
  "status": "open",
  "payment_status": "unpaid",
  "mode": "payment",
  "success_url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://example.com/cancel",
  "customer_id": null,
  "line_items": [
    {
      "price_id": "price_123456789",
      "quantity": 2
    }
  ],
  "expires_at": 1678886400,
  "metadata": {
    "order_id": "order_abc123"
  }
}Retrieve a Checkout Session#Fetches the details of an existing Checkout Session by its ID. This is useful for checking the status after a customer has been redirected.
Parameters
Name
Type
Description
id
string
The unique identifier of the Checkout Session. Required.
Returns
Returns the TCheckoutSessionExpanded object, which includes more details than the standard session object.
Example
async function retrieveCheckoutSession(sessionId) {
  try {
    const session = await payment.checkoutSessions.retrieve(sessionId);
    console.log('Session status:', session.status);
    console.log('Payment status:', session.payment_status);
  } catch (error) {
    console.error('Error retrieving session:', error);
  }
}

retrieveCheckoutSession('cs_xxxxxxxxxxxxxx');Example Response
{
  "id": "cs_xxxxxxxxxxxxxx",
  "object": "checkout.session",
  "status": "complete",
  "payment_status": "paid",
  "mode": "payment",
  "customer_id": "cus_yyyyyyyyyyyyyy",
  "payment_intent_id": "pi_zzzzzzzzzzzzzzz",
  "metadata": {
    "order_id": "order_abc123"
  }
}Update a Checkout Session#Updates an existing Checkout Session. Currently, only the metadata can be modified.
Parameters
Name
Type
Description
id
string
The ID of the Checkout Session to update. Required.
metadata
Object
A set of key-value pairs to store with the session. Any existing metadata will be replaced. Required.
Returns
Returns the updated TCheckoutSession object.
Example
async function updateCheckoutSession(sessionId) {
  try {
    const session = await payment.checkoutSessions.update(sessionId, {
      metadata: { 
        order_id: 'order_abc123',
        shipped: 'false'
      }
    });
    console.log('Updated metadata:', session.metadata);
  } catch (error) {
    console.error('Error updating session:', error);
  }
}

updateCheckoutSession('cs_xxxxxxxxxxxxxx');Example Response
{
  "id": "cs_xxxxxxxxxxxxxx",
  "object": "checkout.session",
  "status": "open",
  "metadata": {
    "order_id": "order_abc123",
    "shipped": "false"
  }
}List all Checkout Sessions#Returns a paginated list of all Checkout Sessions. You can filter the list based on various criteria.
Parameters
Name
Type
Description
status
string
Filter by session status ('open', 'complete', or 'expired'). Optional.
payment_status
string
Filter by payment status ('paid', 'unpaid', or 'no_payment_required'). Optional.
customer_id
string
Only return sessions for the given customer ID. Optional.
payment_intent_id
string
Only return the session for the given Payment Intent. Optional.
subscription_id
string
Only return the session for the given Subscription. Optional.
page
number
The page number for pagination. Optional.
pageSize
number
The number of items per page. Defaults to 20. Optional.
Returns
A paginated object containing a list of TCheckoutSessionExpanded objects and a count of total matching records.
Example
async function listCompletedSessions() {
  try {
    const sessions = await payment.checkoutSessions.list({
      status: 'complete',
      limit: 10
    });
    console.log(`Found ${sessions.count} completed sessions.`);
    sessions.list.forEach(session => {
      console.log(`- ${session.id}`);
    });
  } catch (error) {
    console.error('Error listing sessions:', error);
  }
}

listCompletedSessions();Example Response
{
  "count": 5,
  "list": [
    {
      "id": "cs_session_abc",
      "status": "complete",
      "payment_status": "paid"
    },
    {
      "id": "cs_session_def",
      "status": "complete",
      "payment_status": "paid"
    }
  ]
}Expire a Checkout Session#Manually expires an open Checkout Session. Once expired, a customer can no longer complete the payment.
Parameters
Name
Type
Description
id
string
The ID of the Checkout Session to expire. Required.
Returns
Returns the TCheckoutSession object with its status set to expired.
Example
async function expireCheckoutSession(sessionId) {
  try {
    const session = await payment.checkoutSessions.expire(sessionId);
    console.log(`Session ${session.id} status is now: ${session.status}`);
  } catch (error) {
    console.error('Error expiring session:', error);
  }
}

expireCheckoutSession('cs_xxxxxxxxxxxxxx');Example Response
{
  "id": "cs_xxxxxxxxxxxxxx",
  "object": "checkout.session",
  "status": "expired",
  "payment_status": "unpaid",
  "mode": "payment"
}
After managing Checkout Sessions, you may want to learn more about handling Subscriptions or managing Payment Intents.

Attribute	Type	Description
`id`	`string`	Unique identifier for the Checkout Session.
`url`	`string`	The URL to which you should redirect your customer to complete the payment. This is available only after creation.
`status`	`string`	The current status of the session. Can be `'open'`, `'complete'`, or `'expired'`.
`payment_status`	`string`	The payment status for the session. Can be `'paid'`, `'unpaid'`, or `'no_payment_required'`.
`mode`	`string`	The mode of the Checkout Session, determining its purpose. Can be `'payment'`, `'setup'`, or `'subscription'`.
`customer_id`	`string`	The ID of the associated Customer, if one exists.
`subscription_id`	`string`	The ID of the subscription created if the session is in `subscription` mode.
`line_items`	`Array<Object>`	A list of items the customer is purchasing.
`success_url`	`string`	The URL to redirect to after a successful payment.
`cancel_url`	`string`	The URL to redirect to if the customer cancels the payment flow.
`expires_at`	`number`	The Unix timestamp at which the session will expire.
`metadata`	`Object`	A set of key-value pairs that you can attach to the object for your own reference.

Name	Type	Description
`mode`	`string`	The mode of the Checkout Session. Required. Can be `'payment'`, `'setup'`, or `'subscription'`.
`line_items`	`Array<Object>`	A list of line items for the session. Each item object must contain a `price_id` and `quantity`. Required.
`success_url`	`string`	The URL the customer will be directed to after a successful purchase. Required.
`cancel_url`	`string`	The URL the customer will be directed to if they cancel the purchase. Required.
`customer_id`	`string`	ID of an existing customer to associate with this session. Optional.
`payment_method_types`	`Array<string>`	A list of payment method types to accept (e.g., `'stripe'`, `'arcblock'`). Optional.
`allow_promotion_codes`	`boolean`	Enables user-redeemable promotion codes. Optional.
`subscription_data`	`Object`	Data used when `mode` is `'subscription'`, such as `trial_period_days`. Optional.
`metadata`	`Object`	Key-value data to store with the session. Optional.

Name	Type	Description
`status`	`string`	Filter by session status (`'open'`, `'complete'`, or `'expired'`). Optional.
`payment_status`	`string`	Filter by payment status (`'paid'`, `'unpaid'`, or `'no_payment_required'`). Optional.
`customer_id`	`string`	Only return sessions for the given customer ID. Optional.
`payment_intent_id`	`string`	Only return the session for the given Payment Intent. Optional.
`subscription_id`	`string`	Only return the session for the given Subscription. Optional.
`page`	`number`	The page number for pagination. Optional.
`pageSize`	`number`	The number of items per page. Defaults to 20. Optional.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Checkout Sessions

The Checkout Session Object#

Create a Checkout Session#

Retrieve a Checkout Session#

Update a Checkout Session#

List all Checkout Sessions#

Expire a Checkout Session#

Payment Links

Subscriptions

Name	Type	Description
`id`	`string`	The ID of the Checkout Session to update. Required.
`metadata`	`Object`	A set of key-value pairs to store with the session. Any existing metadata will be replaced. Required.