BiasDocs

Checkout sessions

Checkout sessions represent your customer’s journey through the purchase flow when using Checkout. Your integration should create a new checkout session each time a customer begins the purchase process.

The CheckoutSession object

Name
object
Type
"checkout_session",
Description
Literal representing the object’s type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
live
Type
boolean,
Description
Has the value true if the object exists in a production environment or the value false if the object exists in a sandbox environment.
Name
created_at
Type
integer,
Description
Time at which the object was created. Measured in milliseconds since the Unix epoch.
Name
amount
Type
integer,
Description
The total of the checkout session in cents.
Name
amount_collected
Type
integer,
Description
The amount collected from the customer in successful payments.
Name
billing_details
Type
object or null,
Description
The session’s billing information.
Properties
Name
client_details
Type
object or null,
Description
Information about the client that initiated the checkout session. Populated automatically from the client environment.
Properties
Name
client_secret
Type
string,
Description
The client secret for the checkout session. Return this value to checkout elements to initialize the payment form.
Name
customer
Type
string or Customer or null,
Description
Expandable. The customer associated with the checkout session.
Name
customer_details
Type
object,
Description
The customer’s details entered in this session. When the session completes, the created customer will inherit these values.
Properties
Name
dual_pricing
Type
object or null,
Description
Dual pricing settings for the checkout session. When present, card payments are charged above the session amount using this percentage, while non-card payment methods use the session amount as-is.
Properties
Name
invoice
Type
string or Invoice or null,
Description
Expandable. The invoice this checkout session was created from.
Name
line_items
Type
array of LineItems or null,
Description
The line items representing the products or services being purchased.
Name
metadata
Type
object,
Description
A key-value store that is attached to the object. Useful for storing miscellaneous structured data for your integration’s internal use.
Name
mode
Type
enum,
Description
The mode of the session determines if payment methods are saved and when the customer is charged.
Properties
Name
payment_method_types
Type
array of enums,
Description
The payment method types accepted by this checkout session.
Properties
Name
payments
Type
array of Payments or null or null,
Description
Expandable. The payments associated with the checkout session.
Name
shipping_cost
Type
object or null,
Description
The selected shipping rate and its amount.
Properties
Name
shipping_details
Type
object or null,
Description
The session’s delivery information.
Properties
Name
shipping_options
Type
array of objects,
Description
The shipping options the customer can choose from.
Properties
Name
status
Type
enum,
Description
The status of the session.
Properties
Name
submit_label
Type
enum,
Description
Specify the submit intent for the session. Used to adjust the text on Checkout components to reflect the type of purchase.
Properties
Name
success_url
Type
string or null,
Description
The URL to redirect the customer to after the checkout session is completed.

The CheckoutSession object

{
  "object": "checkout_session",
  "id": "cs_MyJuJvswjRM54vPXr6qBh2",
  "live": false,
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_collected": 1000,
  "dual_pricing": null,
  "client_details": null,
  "client_secret": "uEyLI6rmFylTwIBik5cpn8ge",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "customer_details": {
    "email": null,
    "name": null,
    "phone": null
  },
  "shipping_cost": null,
  "shipping_details": null,
  "shipping_options": [],
  "billing_details": null,
  "payments": [],
  "invoice": null,
  "line_items": [],
  "metadata": {},
  "mode": "payment",
  "payment_method_types": [
    "card",
    "us_bank_account"
  ],
  "status": "complete",
  "submit_label": "auto",
  "success_url": null
}

Get a checkout session

Retrieve a checkout session by its ID.

Required parameters

Name
id
Type
string,
Description
The ID of the checkout session to retrieve.

Optional parameters

Name
expand
Type
object,
Properties

Returns

Returns the checkout session object.

Retrieve a checkout session

const checkoutSession = await bias.checkoutSessions.get("id");

Response example

{
  "object": "checkout_session",
  "id": "cs_MyJuJvswjRM54vPXr6qBh2",
  "live": false,
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_collected": 1000,
  "dual_pricing": null,
  "client_details": null,
  "client_secret": "uEyLI6rmFylTwIBik5cpn8ge",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "customer_details": {
    "email": null,
    "name": null,
    "phone": null
  },
  "shipping_cost": null,
  "shipping_details": null,
  "shipping_options": [],
  "billing_details": null,
  "payments": [],
  "invoice": null,
  "line_items": [],
  "metadata": {},
  "mode": "payment",
  "payment_method_types": [
    "card",
    "us_bank_account"
  ],
  "status": "complete",
  "submit_label": "auto",
  "success_url": null
}

List all checkout sessions

Retrieve a paginated list of checkout sessions.

Optional parameters

Name
expand
Type
object,
Properties
Name
ending_before
Type
string,
Description
A cursor for use in pagination. ending_before is an object ID that results will end before. Used to move backward through the list.
Name
starting_after
Type
string,
Description
A cursor for use in pagination. starting_after is an object ID that results will start after. Used to move forward through the list.
Name
limit
Type
number, at least 1, at most 1000, default is 50
Description
Maximum number of objects to return.
Name
filters
Type
object, object, or object,
Description
Filters to apply to the list. Combine multiple conditions with and and or.
Properties

Returns

Returns a list of checkout session objects.

List all checkout sessions

const checkoutSession = await bias.checkoutSessions.list();

Response example

{
  "object": "list",
  "items": {
    "object": "checkout_session",
    "id": "cs_MyJuJvswjRM54vPXr6qBh2",
    "live": false,
    "created_at": 1750000000000,
    "amount": 1000,
    "amount_collected": 1000,
    "dual_pricing": null,
    "client_details": null,
    "client_secret": "uEyLI6rmFylTwIBik5cpn8ge",
    "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
    "customer_details": {
      "email": null,
      "name": null,
      "phone": null
    },
    "shipping_cost": null,
    "shipping_details": null,
    "shipping_options": [],
    "billing_details": null,
    "payments": [],
    "invoice": null,
    "line_items": [],
    "metadata": {},
    "mode": "payment",
    "payment_method_types": [
      "card",
      "us_bank_account"
    ],
    "status": "complete",
    "submit_label": "auto",
    "success_url": null
  },
  "has_more": false
}

Create a checkout session

Create a new checkout session in response to a customer purchase intent. Return client_secret to the browser for use with checkout elements.

Optional parameters

Name
expand
Type
object,
Properties
Name
amount
Type
integer or null,
Description
Amount in cents for this session. Mutually exclusive with line_items and invoice.
Name
line_items
Type
array of objects or null,
Description
The line items representing the products or services being purchased.
Properties
Name
customer
Type
string,
Description
Expandable. The customer associated with the checkout session.
Name
customer_details
Type
object,
Description
The customer’s details entered in this session. When the session completes, the created customer will inherit these values.
Properties
Name
shipping_details
Type
object or null,
Description
The session’s delivery information.
Properties
Name
shipping_options
Type
array of string or object or null,
Description
Array of existing shipping rate IDs or shipping rate objects to create.
Properties
Name
invoice
Type
string,
Description
Expandable. The invoice this checkout session was created from.
Name
dual_pricing
Type
object or null,
Description
Dual pricing settings for the checkout session. When present, card payments are charged above the session amount using this percentage, while non-card payment methods use the session amount as-is.
Properties
Name
metadata
Type
object or null,
Description
A key-value store that is attached to the object. Useful for storing miscellaneous structured data for your integration’s internal use.
Name
mode
Type
enum,
Description
The mode of the session determines if payment methods are saved and when the customer is charged.
Properties
Name
payment_method_types
Type
array of enums,
Description
The payment method types to accept for this session.
Properties
Name
submit_label
Type
enum,
Description
Specify the submit intent for the session. Used to adjust the text on Checkout components to reflect the type of purchase.
Properties
Name
success_url
Type
string or null,
Description
The URL to redirect the customer to after the checkout session is completed.

Returns

Returns the checkout session object.

Create a checkout session

const checkoutSession = await bias.checkoutSessions.create({
  customer: "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  line_items: [
    {
      price: "price_dz1NVvl5CSogERkeA9Ng67",
      quantity: 2
    }
  ]
});

Response example

{
  "object": "checkout_session",
  "id": "cs_MyJuJvswjRM54vPXr6qBh2",
  "live": false,
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_collected": 1000,
  "dual_pricing": null,
  "client_details": null,
  "client_secret": "uEyLI6rmFylTwIBik5cpn8ge",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "customer_details": {
    "email": null,
    "name": null,
    "phone": null
  },
  "shipping_cost": null,
  "shipping_details": null,
  "shipping_options": [],
  "billing_details": null,
  "payments": [],
  "invoice": null,
  "line_items": [],
  "metadata": {},
  "mode": "payment",
  "payment_method_types": [
    "card",
    "us_bank_account"
  ],
  "status": "complete",
  "submit_label": "auto",
  "success_url": null
}

Expire a checkout session

Expire a checkout session, invalidating it and preventing further payments from being created with it.

Required parameters

Name
id
Type
string,

Returns

Returns the checkout session object.

Expire a checkout session

const checkoutSession = await bias.checkoutSessions.expire("id");

Response example

{
  "object": "checkout_session",
  "id": "cs_MyJuJvswjRM54vPXr6qBh2",
  "live": false,
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_collected": 1000,
  "dual_pricing": null,
  "client_details": null,
  "client_secret": "uEyLI6rmFylTwIBik5cpn8ge",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "customer_details": {
    "email": null,
    "name": null,
    "phone": null
  },
  "shipping_cost": null,
  "shipping_details": null,
  "shipping_options": [],
  "billing_details": null,
  "payments": [],
  "invoice": null,
  "line_items": [],
  "metadata": {},
  "mode": "payment",
  "payment_method_types": [
    "card",
    "us_bank_account"
  ],
  "status": "complete",
  "submit_label": "auto",
  "success_url": null
}

Update a checkout session

Update the properties of a requires_confirmation checkout session. Only the metadata can be updated on checkout sessions that have already been confirmed.

Required parameters

Name
id
Type
string,
Description
The ID of the checkout session to update.

Optional parameters

Name
expand
Type
object,
Properties
Name
amount
Type
integer or null,
Description
Amount in cents for this session. Mutually exclusive with line_items. Can only be used if the session was not created with line items.
Name
line_items
Type
array of object or object,
Description
The line items representing what is being purchased
Properties
Name
customer
Type
string,
Description
The customer's associated with the session.
Name
customer_details
Type
object,
Description
The customer’s details entered in this session. When the session completes, the created customer will inherit these values.
Properties
Name
shipping_details
Type
object or null,
Description
The session’s delivery information.
Properties
Name
billing_details
Type
object or null,
Description
The session’s billing information.
Properties
Name
shipping_options
Type
array of string or object or null,
Description
The shipping options the customer can choose from. Replaces all existing shipping options. Omit or pass null to leave existing shipping options unchanged.
Properties
Name
shipping_rate
Type
string or null,
Description
The selected shipping rate, chosen from the session's shipping options. Pass null to clear the current selection.
Name
dual_pricing
Type
object or null,
Description
Dual pricing settings for the checkout session. When present, card payments are charged above the session amount using this percentage, while non-card payment methods use the session amount as-is.
Properties
Name
metadata
Type
object or null,
Description
A key-value store that is attached to the object. Useful for storing miscellaneous structured data for your integration’s internal use.

Returns

Returns the checkout session object.

Update a checkout session

const checkoutSession = await bias.checkoutSessions.update("id", {
  line_items: [
    {
      id: "li_rbw8iroSXBkFMZ8bisSxK",
      quantity: 3
    },
    {
      price: "price_dz1NVvl5CSogERkeA9Ng67",
      quantity: 1
    }
  ],
  customer: "cus_aB4DEXqbFGOlpEOxwp0Fx1"
});

Response example

{
  "object": "checkout_session",
  "id": "cs_MyJuJvswjRM54vPXr6qBh2",
  "live": false,
  "created_at": 1750000000000,
  "amount": 1000,
  "amount_collected": 1000,
  "dual_pricing": null,
  "client_details": null,
  "client_secret": "uEyLI6rmFylTwIBik5cpn8ge",
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "customer_details": {
    "email": null,
    "name": null,
    "phone": null
  },
  "shipping_cost": null,
  "shipping_details": null,
  "shipping_options": [],
  "billing_details": null,
  "payments": [],
  "invoice": null,
  "line_items": [],
  "metadata": {},
  "mode": "payment",
  "payment_method_types": [
    "card",
    "us_bank_account"
  ],
  "status": "complete",
  "submit_label": "auto",
  "success_url": null
}