Checkout

The Checkout API enables AI agents to create, update, and complete checkout sessions on behalf of buyers. This merchant-implemented REST interface provides a stateful checkout flow with comprehensive cart management, fulfillment options, and payment processing.

Overview

The Checkout API is designed for ChatGPT-driven checkout processes and provides:

  • Session management: Create and maintain checkout state across multiple interactions
  • Cart operations: Add, remove, or update items with automatic price and tax calculations
  • Fulfillment handling: Present shipping options with estimated delivery times
  • Payment processing: Secure payment completion with Stripe integration
  • State synchronization: Each API call returns the latest authoritative checkout state

All API endpoints use HTTPS and return JSON. The merchant maintains full control over inventory, pricing, tax calculations, and payment processing.

Authentication

All API requests must be authenticated using a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

The bearer token should be issued by the merchant and validated on each request to ensure authorized access to checkout operations.

Headers

Required headers

All API requests must include these headers:

HeaderDescription
AuthorizationBearer token for API authentication (e.g., Bearer sk_live_123)
Content-TypeMust be application/json for requests with a body
API-VersionAPI version date in format YYYY-MM-DD (e.g., 2025-12-11)

Optional headers

These headers provide additional functionality:

HeaderDescription
Idempotency-KeyUnique key to safely retry requests without duplicate processing
Request-IdUnique identifier for request tracking and debugging
Accept-LanguagePreferred language for response messages (e.g., en-US)
User-AgentClient application identifier
SignatureHMAC signature for webhook verification
TimestampUnix timestamp for request timing validation

Response headers

The API returns these headers with responses:

HeaderDescription
Idempotency-KeyEcho of the request's idempotency key if provided
Request-IdUnique identifier for the request

Endpoints

Create checkout session

Creates a new checkout session with items and optional buyer information.

This endpoint initializes a new checkout session from a list of items. The response includes the complete checkout state with line items, pricing calculations, available fulfillment options, and any validation messages.

buyerBuyer

Buyer information including first name, last name, email, and optional phone number.

itemsItem[]

Array of items to add to the checkout. Must include at least 1 item. Each item contains an id and quantity.

fulfillment_addressAddress

Shipping address for the order. Required for physical goods.

POST /checkout_sessions
{
  "buyer": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  },
  "items": [
    { "id": "prod_123", "quantity": 2 }
  ],
  "fulfillment_address": {
    "name": "Ada Lovelace",
    "line_one": "123 Market St",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94103"
  }
}

Status Codes:

  • 201 Created - Checkout session successfully created
  • 400 Bad Request - Invalid request parameters or malformed data
  • 401 Unauthorized - Missing or invalid authentication credentials
  • 422 Unprocessable Entity - Valid request but business logic prevents processing (e.g., out of stock)

Retrieve checkout session

Retrieves the current state of an existing checkout session.

This endpoint returns the latest authoritative state for a specific checkout session. Use this to verify current pricing, fulfillment options, or session status.

checkout_session_idstring

The unique identifier for the checkout session.

GET /checkout_sessions/cs_123

Status Codes:

  • 200 OK - Checkout session successfully retrieved
  • 401 Unauthorized - Missing or invalid authentication credentials
  • 404 Not Found - Checkout session does not exist

Update checkout session

Updates an existing checkout session with new items, fulfillment address, or fulfillment option selection.

This endpoint applies changes to the checkout session and returns the updated state. You can update items, select a fulfillment option, modify the shipping address, or update buyer information. All parameters are optional; only include the fields you want to change.

checkout_session_idstring

The unique identifier for the checkout session.

buyerBuyer

Updated buyer information.

itemsItem[]

Updated array of items. This replaces the entire items list.

fulfillment_addressAddress

Updated shipping address.

fulfillment_option_idstring

ID of the selected fulfillment option from the available options.

POST /checkout_sessions/cs_123
{
  "items": [
    { "id": "prod_123", "quantity": 3 }
  ],
  "fulfillment_option_id": "ship_std"
}

Status Codes:

  • 200 OK - Checkout session successfully updated
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication credentials
  • 404 Not Found - Checkout session does not exist
  • 422 Unprocessable Entity - Valid request but business logic prevents update

Complete checkout session

Finalizes the checkout by processing payment and creating an order.

This endpoint completes the checkout session by processing the payment method provided. The merchant must create an order and return it in the response. For Stripe integration, use the Shared Payment Token (SPT) to create and confirm a PaymentIntent.

checkout_session_idstring

The unique identifier for the checkout session.

buyerBuyer

Updated buyer information if needed.

payment_dataPaymentData

Payment method information including token, provider, and optional billing address.

POST /checkout_sessions/cs_123/complete
{
  "payment_data": {
    "token": "spt_1234567890abcdef",
    "provider": "stripe"
  }
}

Status Codes:

  • 200 OK - Checkout successfully completed and order created
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication credentials
  • 402 Payment Required - Payment processing failed
  • 404 Not Found - Checkout session does not exist
  • 409 Conflict - Checkout session already completed or canceled
  • 422 Unprocessable Entity - Valid request but payment cannot be processed (see messages array for details)

Cancel checkout session

Cancels an active checkout session.

This endpoint cancels a checkout session that has not been completed. Use this to release inventory and clean up resources when a buyer exits the checkout process. Sessions that are already completed or canceled cannot be canceled.

checkout_session_idstring

The unique identifier for the checkout session to cancel.

POST /checkout_sessions/cs_123/cancel

Status Codes:

  • 200 OK - Checkout session successfully canceled
  • 401 Unauthorized - Missing or invalid authentication credentials
  • 404 Not Found - Checkout session does not exist
  • 405 Method Not Allowed - Checkout session is already completed or canceled

Schema objects

Below are the canonical JSON Schemas for Checkout objects, rendered object-by-object from the schema bundle.

Address

namestring

Full name of the recipient.

line_onestring

Primary street address line.

line_twostring

Apartment, suite, or unit.

citystring

City or locality.

statestring

State, province, or region.

countrystring

Country or region.

postal_codestring

ZIP or postal code.

{
  "name": "Ada Lovelace",
  "line_one": "123 Market St",
  "line_two": "Apt 4B",
  "city": "San Francisco",
  "state": "CA",
  "country": "US",
  "postal_code": "94103"
}

Buyer

first_namestring
last_namestring
emailstring
Email address
phone_numberstring

{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "phone_number": "+1-555-555-5555"
}

Item

idstring
quantityinteger

{
  "id": "prod_123",
  "quantity": 2
}

PaymentProvider

providerstring
One of: "stripe"
supported_payment_methodsstring[]
Values include "card"

{
  "provider": "stripe",
  "supported_payment_methods": ["card"]
}

LineItem

idstring
itemItem
base_amountinteger
discountinteger
subtotalinteger
taxinteger
totalinteger

{
  "id": "li_123",
  "item": { "id": "prod_123", "quantity": 1 },
  "base_amount": 2000,
  "discount": 0,
  "subtotal": 2000,
  "tax": 160,
  "total": 2160
}

Total

typestring
One of: items_base_amount, items_discount, subtotal, discount, fulfillment, tax, fee, total
display_textstring
amountinteger

{
  "type": "subtotal",
  "display_text": "Subtotal",
  "amount": 2000
}

FulfillmentOptionShipping

typestring
Must be "shipping"
idstring
titlestring
subtitlestring
carrierstring
earliest_delivery_timestring
ISO 8601 date-time
latest_delivery_timestring
ISO 8601 date-time
subtotalinteger
taxinteger
totalinteger

{
  "type": "shipping",
  "id": "ship_std",
  "title": "Standard Shipping",
  "subtitle": "3-5 business days",
  "carrier": "UPS",
  "earliest_delivery_time": "2025-10-26T00:00:00Z",
  "latest_delivery_time": "2025-10-28T00:00:00Z",
  "subtotal": 500,
  "tax": 40,
  "total": 540
}

FulfillmentOptionDigital

typestring
Must be "digital"
idstring
titlestring
subtitlestring
subtotalinteger
taxinteger
totalinteger

{
  "type": "digital",
  "id": "digital_instant",
  "title": "Instant Delivery",
  "subtitle": "Delivered via email",
  "subtotal": 0,
  "tax": 0,
  "total": 0
}

MessageInfo

typestring
Must be "info"
paramstring
RFC 9535 JSONPath
content_typestring
One of: plain, markdown
contentstring

{
  "type": "info",
  "param": "$.buyer.email",
  "content_type": "plain",
  "content": "We use your email for receipts only."
}

MessageError

typestring
Must be "error"
codestring
One of: missing, invalid, out_of_stock, payment_declined, requires_sign_in, requires_3ds
paramstring
RFC 9535 JSONPath
content_typestring
One of: plain, markdown
contentstring

{
  "type": "error",
  "code": "invalid",
  "param": "$.items[0].quantity",
  "content_type": "plain",
  "content": "Quantity must be at least 1."
}

typestring
One of: terms_of_use, privacy_policy, return_policy
urlstring
URI

{
  "type": "terms_of_use",
  "url": "https://example.com/terms"
}

PaymentData

tokenstring
providerstring
Must be "stripe"
billing_addressAddress

{
  "token": "tok_visa_123",
  "provider": "stripe",
  "billing_address": {
    "name": "Ada Lovelace",
    "line_one": "123 Market St",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94103"
  }
}

Order

idstring
checkout_session_idstring
permalink_urlstring
URI

{
  "id": "order_123",
  "checkout_session_id": "cs_123",
  "permalink_url": "https://example.com/orders/order_123"
}

Refund

typestring
One of: store_credit, original_payment
amountinteger

{
  "type": "original_payment",
  "amount": 500
}

CheckoutSessionBase

idstring
buyerBuyer
payment_providerPaymentProvider
statusstring
One of: not_ready_for_payment, ready_for_payment, completed, canceled, in_progress
currencystring
line_itemsLineItem[]
fulfillment_addressAddress
fulfillment_options(FulfillmentOptionShipping|FulfillmentOptionDigital)[]
fulfillment_option_idstring
totalsTotal[]
messages(MessageInfo|MessageError)[]
linksLink[]

{
  "id": "cs_123",
  "buyer": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  },
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "li_123",
      "item": { "id": "prod_123", "quantity": 1 },
      "base_amount": 2000,
      "discount": 0,
      "subtotal": 2000,
      "tax": 160,
      "total": 2160
    }
  ],
  "fulfillment_address": {
    "name": "Ada Lovelace",
    "line_one": "123 Market St",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94103"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "ship_std",
      "title": "Standard Shipping",
      "subtotal": 500,
      "tax": 40,
      "total": 540
    },
    {
      "type": "digital",
      "id": "digital_instant",
      "title": "Instant Delivery",
      "subtotal": 0,
      "tax": 0,
      "total": 0
    }
  ],
  "fulfillment_option_id": "ship_std",
  "totals": [
    { "type": "subtotal", "display_text": "Subtotal", "amount": 2000 },
    { "type": "tax", "display_text": "Tax", "amount": 160 },
    { "type": "fulfillment", "display_text": "Shipping", "amount": 540 },
    { "type": "total", "display_text": "Total", "amount": 2700 }
  ],
  "messages": [],
  "links": [
    { "type": "terms_of_use", "url": "https://example.com/terms" },
    { "type": "privacy_policy", "url": "https://example.com/privacy" }
  ]
}

CheckoutSession

CheckoutSessionCheckoutSessionBase

{
  "id": "cs_123",
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [],
  "totals": [],
  "fulfillment_options": [],
  "messages": [],
  "links": []
}

CheckoutSessionWithOrder

idstring
statusstring
currencystring
line_itemsLineItem[]
totalsTotal[]
fulfillment_options(FulfillmentOptionShipping|FulfillmentOptionDigital)[]
messages(MessageInfo|MessageError)[]
linksLink[]
orderOrder

{
  "id": "cs_123",
  "status": "completed",
  "currency": "usd",
  "line_items": [],
  "totals": [],
  "fulfillment_options": [],
  "messages": [],
  "links": [],
  "order": {
    "id": "order_123",
    "checkout_session_id": "cs_123",
    "permalink_url": "https://example.com/orders/order_123"
  }
}

CheckoutSessionCreateRequest

buyerBuyer
itemsItem[]
Must include at least 1 item
fulfillment_addressAddress

{
  "buyer": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  },
  "items": [
    { "id": "prod_123", "quantity": 1 }
  ],
  "fulfillment_address": {
    "name": "Ada Lovelace",
    "line_one": "123 Market St",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94103"
  }
}

CheckoutSessionUpdateRequest

buyerBuyer
itemsItem[]
fulfillment_addressAddress
fulfillment_option_idstring

{
  "items": [
    { "id": "prod_123", "quantity": 3 }
  ],
  "fulfillment_option_id": "ship_std"
}

CheckoutSessionCompleteRequest

buyerBuyer
payment_dataPaymentData

{
  "payment_data": {
    "token": "tok_visa_123",
    "provider": "stripe"
  }
}

Error

typestring
One of: invalid_request, request_not_idempotent, processing_error, service_unavailable
codestring
Implementation-defined error code
messagestring
paramstring
RFC 9535 JSONPath (optional)

{
  "type": "invalid_request",
  "code": "invalid_email",
  "message": "Email address is invalid",
  "param": "$.buyer.email"
}