Skip to main content
POST
/
api
/
storefront
/
checkout
Create Checkout
curl --request POST \
  --url https://api.example.com/api/storefront/checkout \
  --header 'Content-Type: application/json' \
  --header 'X-Site-ID: <x-site-id>' \
  --data '
{
  "cart_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "email": "jsmith@example.com",
  "shipping_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "company": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>",
    "phone": "<string>"
  },
  "billing_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "company": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>",
    "phone": "<string>"
  },
  "shipping_rate_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cart_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "email": "<string>",
  "shipping_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "company": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>",
    "phone": "<string>"
  },
  "billing_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "company": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>",
    "phone": "<string>"
  },
  "items": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "variant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "product_name": "<string>",
      "variant_name": "<string>",
      "sku": "<string>",
      "image_url": "<string>",
      "price": "<string>",
      "quantity": 123,
      "total": "<string>"
    }
  ],
  "subtotal": "<string>",
  "tax_amount": "<string>",
  "shipping_amount": "<string>",
  "total": "<string>",
  "currency": "<string>",
  "status": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "access_token": "<string>",
  "access_token_expires_at": "2023-11-07T05:31:56Z",
  "payment_intent_id": "<string>",
  "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "completed_at": "2023-11-07T05:31:56Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.stella-commerce.com/llms.txt

Use this file to discover all available pages before exploring further.

Headers

​
X-Site-ID
string
required
​
X-Stella-Token
string | null

Body

application/json

Schema for creating checkout.

​
cart_id
string<uuid>
required
​
email
string<email>
required
​
shipping_address
AddressSchema · object
required

Schema for address. Fields are optional to support simpler address formats from AI widget.

​
billing_address
AddressSchema · object

Schema for address. Fields are optional to support simpler address formats from AI widget.

​
shipping_rate_id
string<uuid> | null

Response

Successful Response

Returned ONLY from POST /api/storefront/checkout.

Layers access_token (the freshly-minted chk_… Bearer for the checkout-web SPA) on top of the standard CheckoutResponse. The plaintext is shown EXACTLY ONCE; subsequent reads via GET /api/storefront/checkout/{id} use the Authorization header and never echo the token back.

​
id
string<uuid>
required
​
cart_id
string<uuid>
required
​
email
string
required
​
shipping_address
AddressSchema · object
required

Schema for address. Fields are optional to support simpler address formats from AI widget.

​
billing_address
AddressSchema · object
required

Schema for address. Fields are optional to support simpler address formats from AI widget.

​
items
CartItemResponse · object[]
required
​
subtotal
string
required
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
​
tax_amount
string
required
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
​
shipping_amount
string
required
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
​
total
string
required
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
​
currency
string
required
​
status
string
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
access_token
string
required
​
access_token_expires_at
string<date-time>
required
​
payment_intent_id
string | null
​
order_id
string<uuid> | null
​
completed_at
string<date-time> | null