Create sessionPOST

OpenStock Docs

POST

/api/checkout-api/sessions

checkout_api100 requests / hour

Creates a hosted checkout session and returns the URL to redirect your customer to. Pass either line_items (custom priced items) or product_ids (products from your store, delivered automatically) — not both.

Keys with no permissions at all are accepted by the Checkout API for backwards compatibility.

Authorization#

AuthorizationBearer <token>

In: header. A store API key starting with sk_ that has the checkout_api permission.

Request body#

application/json

line_itemsobject[]

Custom items with their own name and price. Required unless product_ids is set.

namerequiredstring

Item name shown at checkout.

pricerequirednumber

Unit price in the store currency.

quantityinteger

Positive integer. Default: 1

descriptionstring

Optional line description.

image_urlstring

Optional image shown next to the item.

product_idsobject[]

Products from your store. Stock is checked and delivery is handled for you. Required unless line_items is set.

idrequiredstring

Product ID.

quantityinteger

Positive integer, limited by available stock. Default: 1

variant_idstring

Variant ID for products with variants.

variant_name_or_idstring

Alternative to variant_id: matches a variant by ID or case-insensitive name.

customer_emailstring

Prefills the email field at checkout.

customer_namestring

Prefills the customer name.

success_urlstring

Where the customer lands after paying.

cancel_urlstring

Where the customer lands if they abandon checkout.

expired_urlstring

Where the customer is sent if the session has expired.

webhook_urlstring

Receives checkout.session.* events for this session.

expires_in_secondsnumber

Session lifetime in seconds. Takes precedence over expires_in_hours.

expires_in_hoursnumber

Session lifetime in hours. Default: 24

metadataobject

Key/value pairs echoed back in webhooks.

client_reference_idstring

Your own identifier for this checkout, echoed back in webhooks.

hide_navbarboolean

Hide the store navbar on the checkout page. Default: false

hide_footerboolean

Hide the store footer on the checkout page. Default: false

disable_couponsboolean

Prevent coupon codes for this session. Default: false

disable_gift_cardsboolean

Prevent gift card redemption for this session. Default: false

Responses#

201Session created.
400Invalid body, unknown product, unavailable product or insufficient stock.
401Missing, malformed, disabled or expired API key.
429The hourly limit for this key was reached.

curl -X POST "https://openstock.dev/api/checkout-api/sessions" \
  -H "Authorization: Bearer $OPENSTOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "name": "Premium License",
        "price": 29.99,
        "quantity": 1
      }
    ],
    "customer_email": "jane@example.com",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "webhook_url": "https://example.com/webhooks/checkout",
    "expires_in_seconds": 1800,
    "metadata": {
      "orderNumber": "ORD-4821"
    }
  }'

Session created.

{
  "id": "cs_9f2c4e1a7b3d4c5e8f90a1b2c3d4e5f6",
  "url": "https://your-store.openstock.dev/checkout?session=cs_9f2c4e1a7b3d4c5e8f90a1b2c3d4e5f6",
  "status": "pending",
  "total_amount": 29.99,
  "currency": "USD",
  "expires_at": "2026-03-04T18:50:00.000Z",
  "line_items": 1
}

Request body#

application/json

line_itemsobject[]

Custom items with their own name and price. Required unless product_ids is set.

namerequiredstring

Item name shown at checkout.

pricerequirednumber

Unit price in the store currency.

quantityinteger

Positive integer. Default: 1

descriptionstring

Optional line description.

image_urlstring

Optional image shown next to the item.

product_idsobject[]

Products from your store. Stock is checked and delivery is handled for you. Required unless line_items is set.

idrequiredstring

Product ID.

quantityinteger

Positive integer, limited by available stock. Default: 1

variant_idstring

Variant ID for products with variants.

variant_name_or_idstring

Alternative to variant_id: matches a variant by ID or case-insensitive name.

customer_emailstring

Prefills the email field at checkout.

customer_namestring

Prefills the customer name.

success_urlstring

Where the customer lands after paying.

cancel_urlstring

Where the customer lands if they abandon checkout.

expired_urlstring

Where the customer is sent if the session has expired.

webhook_urlstring

Receives checkout.session.* events for this session.

expires_in_secondsnumber

Session lifetime in seconds. Takes precedence over expires_in_hours.

expires_in_hoursnumber

Session lifetime in hours. Default: 24

metadataobject

Key/value pairs echoed back in webhooks.

client_reference_idstring

Your own identifier for this checkout, echoed back in webhooks.

hide_navbarboolean

Hide the store navbar on the checkout page. Default: false

hide_footerboolean

Hide the store footer on the checkout page. Default: false

disable_couponsboolean

Prevent coupon codes for this session. Default: false

disable_gift_cardsboolean

Prevent gift card redemption for this session. Default: false

curl -X POST "https://openstock.dev/api/checkout-api/sessions" \ -H "Authorization: Bearer $OPENSTOCK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "line_items": [ { "name": "Premium License", "price": 29.99, "quantity": 1 } ], "customer_email": "jane@example.com", "success_url": "https://example.com/success", "cancel_url": "https://example.com/cancel", "webhook_url": "https://example.com/webhooks/checkout", "expires_in_seconds": 1800, "metadata": { "orderNumber": "ORD-4821" } }'

{ "id": "cs_9f2c4e1a7b3d4c5e8f90a1b2c3d4e5f6", "url": "https://your-store.openstock.dev/checkout?session=cs_9f2c4e1a7b3d4c5e8f90a1b2c3d4e5f6", "status": "pending", "total_amount": 29.99, "currency": "USD", "expires_at": "2026-03-04T18:50:00.000Z", "line_items": 1 }