docsAPI ReferenceCheckout Sessions

Checkout Sessions API

The Checkout Sessions API manages shopping carts and purchase flows.

Endpoints

MethodEndpointDescription
POST/checkout_sessionsCreate a new checkout session
GET/checkout_sessions/{id}Get checkout session state
PATCH/checkout_sessions/{id}Update checkout session
POST/checkout_sessions/{id}/completeComplete the purchase
POST/checkout_sessions/{id}/cancelCancel the checkout

Create Checkout Session

Create a new checkout session with cart items.

POST /checkout_sessions

Request Body

FieldTypeRequiredDescription
itemsLineItemInput[]YesItems to add to cart
shipping_addressAddressNoShipping address
customerCustomerNoCustomer information
payment_methodstringNoPayment method (default: demo_card)

LineItemInput

FieldTypeRequiredDescription
product_idstringYesProduct ID from catalog
variant_skustringNoSpecific variant SKU
quantityintegerNoQuantity (default: 1)

Address

FieldTypeRequiredDescription
namestringNoRecipient name
line1stringNoStreet address
line2stringNoApartment, suite, etc.
citystringNoCity
statestringNoState/province code
postal_codestringNoZIP/postal code
countrystringNoCountry code (e.g., US)

Customer

FieldTypeRequiredDescription
emailstringNoCustomer email
phonestringNoCustomer phone
namestringNoCustomer name

Response

Returns a CheckoutSessionResponse with the created session.

Examples

cURL

curl -X POST "https://{{YOUR_STORE_URL}}/checkout_sessions" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}" \
  -d '{
    "items": [
      {
        "product_id": "{{PRODUCT_ID}}",
        "variant_sku": "{{VARIANT_SKU}}",
        "quantity": 1
      }
    ],
    "shipping_address": {
      "name": "Jane Doe",
      "line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US"
    },
    "customer": {
      "email": "jane@example.com",
      "name": "Jane Doe"
    }
  }'

Python

import requests
 
BASE_URL = "https://{{YOUR_STORE_URL}}"
HEADERS = {
    "Content-Type": "application/json",
    "X-ACP-API-Key": "{{YOUR_API_KEY}}"
}
 
def create_checkout(items, shipping_address=None, customer=None):
    payload = {"items": items}
    
    if shipping_address:
        payload["shipping_address"] = shipping_address
    if customer:
        payload["customer"] = customer
    
    response = requests.post(
        f"{BASE_URL}/checkout_sessions",
        json=payload,
        headers=HEADERS
    )
    response.raise_for_status()
    return response.json()
 
# Usage
session = create_checkout(
    items=[
        {"product_id": "prod_abc123", "variant_sku": "sku_black_m", "quantity": 2}
    ],
    shipping_address={
        "name": "Jane Doe",
        "line1": "123 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94102",
        "country": "US"
    },
    customer={
        "email": "jane@example.com",
        "name": "Jane Doe"
    }
)
 
print(f"Session ID: {session['checkout_session']['id']}")
print(f"Total: ${session['checkout_session']['amounts']['total']}")

TypeScript

const BASE_URL = "https://{{YOUR_STORE_URL}}";
const API_KEY = "{{YOUR_API_KEY}}";
 
interface LineItemInput {
  product_id: string;
  variant_sku?: string;
  quantity?: number;
}
 
interface Address {
  name?: string;
  line1?: string;
  line2?: string;
  city?: string;
  state?: string;
  postal_code?: string;
  country?: string;
}
 
interface Customer {
  email?: string;
  phone?: string;
  name?: string;
}
 
interface CreateCheckoutInput {
  items: LineItemInput[];
  shipping_address?: Address;
  customer?: Customer;
}
 
async function createCheckout(input: CreateCheckoutInput): Promise<any> {
  const response = await fetch(`${BASE_URL}/checkout_sessions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-ACP-API-Key": API_KEY
    },
    body: JSON.stringify(input)
  });
 
  if (!response.ok) {
    throw new Error(`Failed to create checkout: ${response.statusText}`);
  }
 
  return response.json();
}
 
// Usage
const session = await createCheckout({
  items: [
    { product_id: "prod_abc123", variant_sku: "sku_black_m", quantity: 2 }
  ],
  shipping_address: {
    name: "Jane Doe",
    line1: "123 Main Street",
    city: "San Francisco",
    state: "CA",
    postal_code: "94102",
    country: "US"
  },
  customer: {
    email: "jane@example.com"
  }
});
 
console.log(`Session ID: ${session.checkout_session.id}`);
console.log(`Total: $${session.checkout_session.amounts.total}`);

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
public class LornCheckoutClient {
    private static final String BASE_URL = "https://{{YOUR_STORE_URL}}";
    private static final String API_KEY = "{{YOUR_API_KEY}}";
    private final HttpClient client = HttpClient.newHttpClient();
 
    public String createCheckout(String requestBody) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/checkout_sessions"))
            .header("Content-Type", "application/json")
            .header("X-ACP-API-Key", API_KEY)
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();
 
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        
        if (response.statusCode() != 200 && response.statusCode() != 201) {
            throw new RuntimeException("Failed to create checkout: " + response.body());
        }
        
        return response.body();
    }
}
 
// Usage
String requestBody = """
{
  "items": [
    {"product_id": "prod_abc123", "variant_sku": "sku_black_m", "quantity": 2}
  ],
  "shipping_address": {
    "name": "Jane Doe",
    "line1": "123 Main Street",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "customer": {"email": "jane@example.com"}
}
""";
 
LornCheckoutClient client = new LornCheckoutClient();
String result = client.createCheckout(requestBody);
System.out.println(result);

Go

package main
 
import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)
 
const (
    baseURL = "https://{{YOUR_STORE_URL}}"
    apiKey  = "{{YOUR_API_KEY}}"
)
 
type LineItemInput struct {
    ProductID  string `json:"product_id"`
    VariantSKU string `json:"variant_sku,omitempty"`
    Quantity   int    `json:"quantity,omitempty"`
}
 
type Address struct {
    Name       string `json:"name,omitempty"`
    Line1      string `json:"line1,omitempty"`
    Line2      string `json:"line2,omitempty"`
    City       string `json:"city,omitempty"`
    State      string `json:"state,omitempty"`
    PostalCode string `json:"postal_code,omitempty"`
    Country    string `json:"country,omitempty"`
}
 
type Customer struct {
    Email string `json:"email,omitempty"`
    Phone string `json:"phone,omitempty"`
    Name  string `json:"name,omitempty"`
}
 
type CreateCheckoutInput struct {
    Items           []LineItemInput `json:"items"`
    ShippingAddress *Address        `json:"shipping_address,omitempty"`
    Customer        *Customer       `json:"customer,omitempty"`
}
 
func createCheckout(input CreateCheckoutInput) (map[string]interface{}, error) {
    body, err := json.Marshal(input)
    if err != nil {
        return nil, err
    }
 
    req, err := http.NewRequest("POST", baseURL+"/checkout_sessions", bytes.NewBuffer(body))
    if err != nil {
        return nil, err
    }
 
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-ACP-API-Key", apiKey)
 
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
 
    respBody, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }
 
    var result map[string]interface{}
    if err := json.Unmarshal(respBody, &result); err != nil {
        return nil, err
    }
 
    return result, nil
}
 
func main() {
    session, err := createCheckout(CreateCheckoutInput{
        Items: []LineItemInput{
            {ProductID: "prod_abc123", VariantSKU: "sku_black_m", Quantity: 2},
        },
        ShippingAddress: &Address{
            Name:       "Jane Doe",
            Line1:      "123 Main Street",
            City:       "San Francisco",
            State:      "CA",
            PostalCode: "94102",
            Country:    "US",
        },
        Customer: &Customer{
            Email: "jane@example.com",
        },
    })
    if err != nil {
        panic(err)
    }
 
    fmt.Printf("Session: %v\n", session)
}

Get Checkout Session

Retrieve the current state of a checkout session.

GET /checkout_sessions/{session_id}

Path Parameters

ParameterTypeRequiredDescription
session_idstringYesCheckout session ID

Response

Returns a CheckoutSessionResponse with the current session state.

Examples

cURL

curl "https://{{YOUR_STORE_URL}}/checkout_sessions/{{SESSION_ID}}" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}"

Python

def get_checkout(session_id: str) -> dict:
    response = requests.get(
        f"{BASE_URL}/checkout_sessions/{session_id}",
        headers=HEADERS
    )
    response.raise_for_status()
    return response.json()
 
# Usage
session = get_checkout("cs_demo_abc123")
print(f"Status: {session['checkout_session']['status']}")
print(f"Total: ${session['checkout_session']['amounts']['total']}")

TypeScript

async function getCheckout(sessionId: string): Promise<any> {
  const response = await fetch(`${BASE_URL}/checkout_sessions/${sessionId}`, {
    headers: { "X-ACP-API-Key": API_KEY }
  });
  
  if (!response.ok) {
    throw new Error(`Checkout not found: ${sessionId}`);
  }
  
  return response.json();
}

Update Checkout Session

Update an existing checkout session (cart items, address, or customer info).

PATCH /checkout_sessions/{session_id}

Path Parameters

ParameterTypeRequiredDescription
session_idstringYesCheckout session ID

Request Body

FieldTypeRequiredDescription
itemsLineItemInput[]NoReplace cart items entirely
shipping_addressAddressNoUpdate shipping address
customerCustomerNoUpdate customer info
payment_methodstringNoUpdate payment method

Note: When items is provided, it replaces the entire cart. Omit to keep existing items.

Response

Returns a CheckoutSessionResponse with the updated session state.

Examples

cURL

# Update shipping address
curl -X PATCH "https://{{YOUR_STORE_URL}}/checkout_sessions/{{SESSION_ID}}" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}" \
  -d '{
    "shipping_address": {
      "name": "Jane Doe",
      "line1": "456 Oak Avenue",
      "city": "Los Angeles",
      "state": "CA",
      "postal_code": "90001",
      "country": "US"
    }
  }'
 
# Update cart items
curl -X PATCH "https://{{YOUR_STORE_URL}}/checkout_sessions/{{SESSION_ID}}" \
  -H "Content-Type: application/json" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}" \
  -d '{
    "items": [
      {"product_id": "prod_abc123", "quantity": 3},
      {"product_id": "prod_xyz789", "quantity": 1}
    ]
  }'

Python

def update_checkout(session_id: str, updates: dict) -> dict:
    response = requests.patch(
        f"{BASE_URL}/checkout_sessions/{session_id}",
        json=updates,
        headers=HEADERS
    )
    response.raise_for_status()
    return response.json()
 
# Update shipping address
session = update_checkout("cs_demo_abc123", {
    "shipping_address": {
        "name": "Jane Doe",
        "line1": "456 Oak Avenue",
        "city": "Los Angeles",
        "state": "CA",
        "postal_code": "90001",
        "country": "US"
    }
})
 
# Update cart quantity
session = update_checkout("cs_demo_abc123", {
    "items": [
        {"product_id": "prod_abc123", "quantity": 3}
    ]
})

TypeScript

async function updateCheckout(sessionId: string, updates: object): Promise<any> {
  const response = await fetch(`${BASE_URL}/checkout_sessions/${sessionId}`, {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      "X-ACP-API-Key": API_KEY
    },
    body: JSON.stringify(updates)
  });
  
  if (!response.ok) {
    throw new Error(`Failed to update checkout: ${response.statusText}`);
  }
  
  return response.json();
}
 
// Update shipping address
const session = await updateCheckout("cs_demo_abc123", {
  shipping_address: {
    name: "Jane Doe",
    line1: "456 Oak Avenue",
    city: "Los Angeles",
    state: "CA",
    postal_code: "90001",
    country: "US"
  }
});

Complete Checkout Session

Finalize the checkout and complete the purchase.

POST /checkout_sessions/{session_id}/complete

Path Parameters

ParameterTypeRequiredDescription
session_idstringYesCheckout session ID

Response

Returns a CheckoutSessionResponse with status: "completed".

Examples

cURL

curl -X POST "https://{{YOUR_STORE_URL}}/checkout_sessions/{{SESSION_ID}}/complete" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}"

Python

def complete_checkout(session_id: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/checkout_sessions/{session_id}/complete",
        headers=HEADERS
    )
    response.raise_for_status()
    return response.json()
 
# Usage
order = complete_checkout("cs_demo_abc123")
print(f"Order completed! Status: {order['checkout_session']['status']}")
print(f"Total charged: ${order['checkout_session']['amounts']['total']}")

TypeScript

async function completeCheckout(sessionId: string): Promise<any> {
  const response = await fetch(
    `${BASE_URL}/checkout_sessions/${sessionId}/complete`,
    {
      method: "POST",
      headers: { "X-ACP-API-Key": API_KEY }
    }
  );
  
  if (!response.ok) {
    throw new Error(`Failed to complete checkout: ${response.statusText}`);
  }
  
  return response.json();
}
 
const order = await completeCheckout("cs_demo_abc123");
console.log(`Order completed! Total: $${order.checkout_session.amounts.total}`);

Cancel Checkout Session

Cancel an in-progress checkout session.

POST /checkout_sessions/{session_id}/cancel

Path Parameters

ParameterTypeRequiredDescription
session_idstringYesCheckout session ID

Response

Returns a CheckoutSessionResponse with status: "canceled".

Errors

StatusErrorDescription
404not_foundSession not found
405method_not_allowedSession already completed or canceled

Examples

cURL

curl -X POST "https://{{YOUR_STORE_URL}}/checkout_sessions/{{SESSION_ID}}/cancel" \
  -H "X-ACP-API-Key: {{YOUR_API_KEY}}"

Python

def cancel_checkout(session_id: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/checkout_sessions/{session_id}/cancel",
        headers=HEADERS
    )
    
    if response.status_code == 405:
        raise ValueError("Cannot cancel: session already completed or canceled")
    
    response.raise_for_status()
    return response.json()
 
# Usage
try:
    result = cancel_checkout("cs_demo_abc123")
    print(f"Session canceled: {result['checkout_session']['status']}")
except ValueError as e:
    print(e)

Response Objects

CheckoutSessionResponse

{
  "checkout_session": {
    "id": "cs_demo_abc123",
    "status": "open",
    "currency": "USD",
    "line_items": [
      {
        "product_id": "prod_abc123",
        "variant_sku": "sku_black_m",
        "quantity": 2,
        "title": "Classic Cotton T-Shirt",
        "unit_price": 29.99,
        "currency": "USD",
        "subtotal": 59.98
      }
    ],
    "shipping_address": {
      "name": "Jane Doe",
      "line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US"
    },
    "customer": {
      "email": "jane@example.com",
      "name": "Jane Doe"
    },
    "payment_method": "demo_card",
    "shipping": {
      "method": "ground",
      "amount": 7.99,
      "currency": "USD"
    },
    "tax": {
      "rate": 0.08,
      "amount": 4.80,
      "currency": "USD"
    },
    "amounts": {
      "subtotal": 59.98,
      "tax": 4.80,
      "shipping": 7.99,
      "total": 72.77,
      "currency": "USD"
    },
    "client_secret": "pi_demo_cs_demo_abc123_secret_demo",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Field Reference

CheckoutSession

FieldTypeDescription
idstringUnique session identifier
statusstringopen, completed, canceled
currencystringCurrency code
line_itemsLineItem[]Cart items
shipping_addressAddressShipping address
customerCustomerCustomer info
payment_methodstringPayment method
shippingShippingQuoteShipping details
taxTaxSummaryTax calculation
amountsAmountBreakdownPrice totals
client_secretstringPayment intent secret
created_atstringCreation timestamp (ISO 8601)

LineItem

FieldTypeDescription
product_idstringProduct ID
variant_skustringVariant SKU
quantityintegerQuantity
titlestringProduct title
unit_pricenumberPrice per unit
currencystringCurrency
subtotalnumberLine total

AmountBreakdown

FieldTypeDescription
subtotalnumberSum of line items
taxnumberTax amount
shippingnumberShipping cost
totalnumberGrand total
currencystringCurrency

Errors

StatusErrorDescription
400invalid_requestInvalid input (missing items, unknown product)
404not_foundSession or product not found
405method_not_allowedInvalid operation (e.g., cancel completed session)
503service_unavailableBackend not configured

Error Response

{
  "detail": "Checkout session not found"
}

See Also

ProductsWebhooks