Skip to main content
POST
/
checkout_sessions
Create checkout session
curl --request POST \
  --url https://api.lava.so/v1/checkout_sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "checkout_mode": "subscription",
  "origin_url": "https://your-app.example.com/",
  "customer_id": "con_test_01KKM3W4FS7GF0QBJ4YYHNPS2C",
  "plan_id": "sc_123",
  "credit_bundle_id": "cb_abc123"
}
'
{
  "checkout_session_id": "cs_test_01KKM3W4FRAEX8BER19F06YW4K",
  "checkout_session_token": "eyJzZWNyZXQiOiJjc3NfdGVzdF9GNHFEQnVYM1FzSGUtTnVuaXJoZGlFR0NubjRFR3dCNUVuUXFZSEwyLVdzLXhyMUNWRFJzMS0xIiwiYmFzZSI6Imh0dHBzOi8vd3d3LmxhdmEuc28vIn0=",
  "checkout_mode": "subscription",
  "origin_url": "https://your-app.example.com/",
  "created_at": "2023-05-15T08:30:00Z",
  "customer_id": "con_test_01KKM3W4FSP0AMHJSB8A4V9BPM",
  "plan_id": "sc_123",
  "completed_at": "2023-05-15T08:35:42Z"
}
For checkout_mode: "subscription", customer_id is optional:
  • Omit it for logged-out/new customers (checkout collects identity and creates a customer)
  • Include it for logged-in/returning customers (checkout reuses the existing customer)
New customer subscription checkout
{
  "checkout_mode": "subscription",
  "origin_url": "https://yourapp.com",
  "plan_id": "sub_plan_id"
}
Returning customer subscription checkout
{
  "checkout_mode": "subscription",
  "origin_url": "https://yourapp.com",
  "plan_id": "sub_plan_id",
  "customer_id": "conn_existing_customer_id"
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication used for standard API calls. Format: 'Bearer YOUR_API_KEY'

Body

application/json
​
checkout_mode
enum<string>
required

Checkout mode: 'subscription' creates a recurring subscription checkout, 'credit_bundle' purchases a credit pack for an existing subscriber

Available options:
subscription,
credit_bundle
Example:

"subscription"

​
origin_url
string<uri>
required

Origin url where the checkout will be opened

Example:

"https://your-app.example.com/"

​
customer_id
string

Required for credit_bundle mode. Optional for subscription mode — omit for new customers (checkout collects identity and creates a customer) or include for returning customers (reuses the existing customer).

Example:

"con_test_01KKM3W4FS7GF0QBJ4YYHNPS2C"

​
plan_id
string

Required when checkout_mode is 'subscription' - identifies the plan to use

Example:

"sc_123"

​
credit_bundle_id
string

Required when checkout_mode is 'credit_bundle' - identifies the credit bundle to purchase

Example:

"cb_abc123"

Response

Checkout session created

​
checkout_session_id
string
required

Unique identifier for the checkout session

Example:

"cs_test_01KKM3W4FRAEX8BER19F06YW4K"

​
checkout_session_token
string
required

Opaque token for the @lavapayments/checkout SDK. Pass this to open() to launch the checkout flow.

Example:

"eyJzZWNyZXQiOiJjc3NfdGVzdF9GNHFEQnVYM1FzSGUtTnVuaXJoZGlFR0NubjRFR3dCNUVuUXFZSEwyLVdzLXhyMUNWRFJzMS0xIiwiYmFzZSI6Imh0dHBzOi8vd3d3LmxhdmEuc28vIn0="

​
checkout_mode
enum<string>
required

Checkout mode: 'subscription' creates a recurring subscription checkout, 'credit_bundle' purchases a credit pack for an existing subscriber

Available options:
subscription,
credit_bundle
Example:

"subscription"

​
origin_url
string
required

Origin url where the checkout will be opened

Example:

"https://your-app.example.com/"

​
created_at
string<date-time>
required

ISO 8601 timestamp when the checkout session was created

Example:

"2023-05-15T08:30:00Z"

​
customer_id
string

Identifier for the customer (only available after checkout completion)

Example:

"con_test_01KKM3W4FSP0AMHJSB8A4V9BPM"

​
plan_id
string

Identifier for the plan (only available for subscription mode)

Example:

"sc_123"

​
completed_at
string<date-time>

If completed, ISO 8601 timestamp when the checkout was completed

Example:

"2023-05-15T08:35:42Z"