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/",
  "connection_id": "con_test_01KK2NQPKARMY7D3HK65C2ZSYK",
  "subscription_config_id": "sc_123",
  "credit_bundle_id": "cb_abc123"
}
'
{
  "checkout_session_id": "cs_test_01KK2NQPK7CXRHEW42Z4X4M06R",
  "checkout_session_token": "eyJzZWNyZXQiOiJjc3NfdGVzdF9uZDFWT284MkZiSHE0U3JpUklsYXVILW91ZldHbVN1eVp6SHhmVVczMXdpd21uM2lCSlJiZG1jIiwiYmFzZSI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMC8ifQ==",
  "checkout_mode": "subscription",
  "origin_url": "https://your-app.example.com/",
  "created_at": "2023-05-15T08:30:00Z",
  "connection_id": "con_test_01KK2NQPK9K6Y6KRFERDXFM56R",
  "subscription_config_id": "sc_123",
  "completed_at": "2023-05-15T08:35:42Z"
}
For checkout_mode: "subscription", connection_id is optional:
  • Omit it for logged-out/new customers (checkout collects identity and creates a connection)
  • Include it for logged-in/returning customers (checkout reuses the existing connection)
New customer subscription checkout
{
  "checkout_mode": "subscription",
  "origin_url": "https://yourapp.com",
  "subscription_config_id": "sub_plan_id"
}
Returning customer subscription checkout
{
  "checkout_mode": "subscription",
  "origin_url": "https://yourapp.com",
  "subscription_config_id": "sub_plan_id",
  "connection_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/"

​
connection_id
string

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

Example:

"con_test_01KK2NQPKARMY7D3HK65C2ZSYK"

​
subscription_config_id
string

Required when checkout_mode is 'subscription' - identifies the subscription configuration 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_01KK2NQPK7CXRHEW42Z4X4M06R"

​
checkout_session_token
string
required

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

Example:

"eyJzZWNyZXQiOiJjc3NfdGVzdF9uZDFWT284MkZiSHE0U3JpUklsYXVILW91ZldHbVN1eVp6SHhmVVczMXdpd21uM2lCSlJiZG1jIiwiYmFzZSI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMC8ifQ=="

​
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"

​
connection_id
string

Identifier for the connection (only available after checkout completion)

Example:

"con_test_01KK2NQPK9K6Y6KRFERDXFM56R"

​
subscription_config_id
string

Identifier for the subscription configuration (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"