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"
}
'import requests
url = "https://api.example.com/api/storefront/checkout"
payload = {
"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"
}
headers = {
"X-Site-ID": "<x-site-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Site-ID': '<x-site-id>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
})
};
fetch('https://api.example.com/api/storefront/checkout', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/storefront/checkout",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Site-ID: <x-site-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/storefront/checkout"
payload := strings.NewReader("{\n \"cart_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"email\": \"jsmith@example.com\",\n \"shipping_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"billing_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"shipping_rate_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Site-ID", "<x-site-id>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/storefront/checkout")
.header("X-Site-ID", "<x-site-id>")
.header("Content-Type", "application/json")
.body("{\n \"cart_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"email\": \"jsmith@example.com\",\n \"shipping_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"billing_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"shipping_rate_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/storefront/checkout")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Site-ID"] = '<x-site-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cart_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"email\": \"jsmith@example.com\",\n \"shipping_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"billing_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"shipping_rate_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Create Checkout
Create a checkout from a cart.
Validates inventory availability + computes tax + stamps shipping
rate (if shipping_rate_id provided). Total reflects subtotal +
tax + shipping at create time so the Stripe payment page sees a
stable amount.
Returns the checkout body PLUS a freshly-minted chk_… access
token. The token is shown EXACTLY ONCE — the storefront should
embed it into the buyer-facing checkout_url (typically as a URL
fragment so it doesn’t leak via Referer headers). The
checkout-web SPA uses it as Authorization: Bearer chk_… to
drive subsequent reads + payment-intent creation.
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"
}
'import requests
url = "https://api.example.com/api/storefront/checkout"
payload = {
"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"
}
headers = {
"X-Site-ID": "<x-site-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Site-ID': '<x-site-id>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
})
};
fetch('https://api.example.com/api/storefront/checkout', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/storefront/checkout",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Site-ID: <x-site-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/storefront/checkout"
payload := strings.NewReader("{\n \"cart_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"email\": \"jsmith@example.com\",\n \"shipping_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"billing_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"shipping_rate_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Site-ID", "<x-site-id>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/storefront/checkout")
.header("X-Site-ID", "<x-site-id>")
.header("Content-Type", "application/json")
.body("{\n \"cart_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"email\": \"jsmith@example.com\",\n \"shipping_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"billing_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"shipping_rate_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/storefront/checkout")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Site-ID"] = '<x-site-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cart_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"email\": \"jsmith@example.com\",\n \"shipping_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"billing_address\": {\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"company\": \"<string>\",\n \"address1\": \"<string>\",\n \"address2\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"country\": \"<string>\",\n \"phone\": \"<string>\"\n },\n \"shipping_rate_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Body
Schema for creating checkout.
Schema for address. Fields are optional to support simpler address formats from AI widget.
Show child attributes
Show child attributes
Schema for address. Fields are optional to support simpler address formats from AI widget.
Show child attributes
Show child attributes
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.
Schema for address. Fields are optional to support simpler address formats from AI widget.
Show child attributes
Show child attributes
Schema for address. Fields are optional to support simpler address formats from AI widget.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$