Skip to main content
POST
/
v1
/
checkout_sessions
Create a Checkout Session
curl --request POST \
  --url https://api.leanrails.com/v1/checkout_sessions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "mode": "payment",
  "line_items": [
    {
      "quantity": 2,
      "price": "<string>",
      "price_data": {
        "currency": "<string>",
        "product": "<string>",
        "unit_amount": 1,
        "tax_behavior": "inclusive",
        "recurring": {
          "interval": "day",
          "interval_count": 1
        }
      }
    }
  ],
  "success_url": "<string>",
  "cancel_url": "<string>",
  "customer": "<string>",
  "customer_email": "jsmith@example.com",
  "customer_creation": "if_required",
  "ui_mode": "hosted",
  "billing_address_collection": "auto",
  "client_reference_id": "<string>",
  "payment_intent_data": {
    "capture_method": "automatic",
    "description": "<string>",
    "statement_descriptor": "<string>",
    "metadata": {},
    "application_fee_amount": 1
  },
  "currency": "<string>",
  "expires_at": 123,
  "metadata": {}
}
'
{
  "id": "cs_xxx",
  "object": "checkout.session",
  "mode": "payment",
  "status": "open",
  "payment_status": "unpaid",
  "ui_mode": "hosted",
  "customer_creation": "always",
  "billing_address_collection": "auto",
  "expires_at": 123,
  "metadata": {},
  "livemode": false,
  "created": 1234567890,
  "url": "<string>",
  "client_secret": "<string>",
  "success_url": "<string>",
  "cancel_url": "<string>",
  "customer": "cus_xxx",
  "customer_email": "<string>",
  "customer_details": {
    "email": "<string>",
    "name": "<string>",
    "phone": "<string>",
    "address": {
      "city": "<string>",
      "country": "<string>",
      "line1": "<string>",
      "line2": "<string>",
      "postal_code": "<string>",
      "state": "<string>"
    }
  },
  "payment_intent": "pi_xxx",
  "currency": "usd",
  "amount_subtotal": 123,
  "amount_total": 123,
  "total_details": {
    "amount_discount": 123,
    "amount_shipping": 123,
    "amount_tax": 123
  },
  "client_reference_id": "<string>"
}

Authorizations

​
Authorization
string
header
required

Use your secret API key as the username with an empty password.

Headers

​
Idempotency-Key
string
required

Unique key to ensure idempotent requests.

Maximum string length: 255
​
X-API-Version
string

Override the API version for this request.

Body

application/json
​
mode
enum<string>
required

The mode of the Checkout Session. Currently only 'payment' is supported.

Available options:
payment
​
line_items
object[]
required

Line items the customer is purchasing. Each must have either price or price_data.

Minimum array length: 1
​
success_url
string<uri>

The URL to redirect to after a successful payment. Required for hosted mode.

​
cancel_url
string<uri>

The URL to redirect to when the customer cancels.

​
customer
string

ID of an existing customer.

Pattern: ^cus_
​
customer_email
string<email>

Pre-fill the customer's email on the checkout page.

​
customer_creation
enum<string>
default:if_required

Whether to always create a customer, or only if required.

Available options:
always,
if_required
​
ui_mode
enum<string>
default:hosted

The UI mode of the session.

Available options:
hosted,
embedded,
custom
​
billing_address_collection
enum<string>
default:auto

Whether to collect billing address.

Available options:
auto,
required
​
client_reference_id
string

A unique string to reference the session in your system.

Maximum string length: 200
​
payment_intent_data
object

Data to pass to the underlying PaymentIntent.

​
currency
string

Override the currency. Defaults to the currency of the line items.

Required string length: 3
​
expires_at
integer

Unix timestamp for when the session expires. Must be between 30 minutes and 24 hours from now.

​
metadata
object

Set of key-value pairs for storing additional information.

Response

The created Checkout Session.

​
id
string
required
Example:

"cs_xxx"

​
object
enum<string>
required
Available options:
checkout.session
​
mode
enum<string>
required

The mode of the Checkout Session.

Available options:
payment,
setup,
subscription
​
status
enum<string>
required

The status of the Checkout Session.

Available options:
open,
complete,
expired
​
payment_status
enum<string>
required

The payment status of the Checkout Session.

Available options:
unpaid,
paid,
no_payment_required
​
ui_mode
enum<string>
required

The UI mode of the session.

Available options:
hosted,
embedded,
custom
​
customer_creation
enum<string>
required

Whether a customer was always created or only if required.

Available options:
always,
if_required
​
billing_address_collection
enum<string>
required

Whether billing address was collected.

Available options:
auto,
required
​
expires_at
integer
required

Unix timestamp for when the session expires.

​
metadata
object
required

Set of key-value pairs for storing additional information.

​
livemode
boolean
required
Example:

false

​
created
integer
required

Unix timestamp.

Example:

1234567890

​
url
string<uri> | null

The URL to the hosted checkout page. Only set for hosted mode.

​
client_secret
string | null

The client secret for embedded/custom mode.

​
success_url
string<uri> | null

The URL to redirect to after successful payment.

​
cancel_url
string<uri> | null

The URL to redirect to when the customer cancels.

​
customer
string | null

The ID of the customer.

Example:

"cus_xxx"

​
customer_email
string | null

The customer's email address.

​
customer_details
object

Customer details collected during checkout.

​
payment_intent
string | null

The ID of the PaymentIntent for this session.

Example:

"pi_xxx"

​
currency
string | null

Three-letter ISO currency code.

Example:

"usd"

​
amount_subtotal
integer | null

Total before discounts and taxes, in smallest currency unit.

​
amount_total
integer | null

Total after discounts and taxes, in smallest currency unit.

​
total_details
object

Breakdown of the total amount.

​
client_reference_id
string | null

A unique string to reference the session.