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:

Header	Description
`Authorization`	Bearer token for API authentication (e.g., `Bearer sk_live_123`)
`Content-Type`	Must be `application/json` for requests with a body
`API-Version`	API version date in format `YYYY-MM-DD` (e.g., `2026-01-30`)

Optional headers

These headers provide additional functionality:

Header	Description
`Idempotency-Key`	Unique key to safely retry requests without duplicate processing
`Request-Id`	Unique identifier for request tracking and debugging
`Accept-Language`	Preferred language for response messages (e.g., `en-US`)
`User-Agent`	Client application identifier
`Signature`	HMAC signature for webhook verification
`Timestamp`	Unix timestamp for request timing validation

Response headers

The API returns these headers with responses:

Header	Description
`Idempotency-Key`	Echo of the request's idempotency key if provided
`Request-Id`	Unique 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": "[email protected]"
  },
  "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": "[email protected]",
  "phone_number": "+1-555-555-5555"
}

Item

idstring

quantityinteger

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

Capabilities

paymentPayment

Payment configuration with handlers

interventionsInterventionCapabilities

Intervention capabilities

extensionsExtensionDeclaration[]

Active extensions for this session

{
  "payment": {
    "handlers": [
      {
        "id": "card_tokenized",
        "name": "dev.acp.tokenized.card",
        "version": "2026-01-22",
        "spec": "https://acp.dev/handlers/tokenized.card",
        "requires_delegate_payment": true,
        "requires_pci_compliance": false,
        "psp": "stripe",
        "config_schema": "https://acp.dev/schemas/handlers/tokenized.card/config.json",
        "instrument_schemas": [
          "https://acp.dev/schemas/handlers/tokenized.card/instrument.json"
        ],
        "config": {
          "merchant_id": "acct_1234567890",
          "accepted_brands": ["visa", "mastercard", "amex", "discover"],
          "supports_3ds": true
        }
      }
    ]
  },
  "interventions": {
    "supported": ["3ds"],
    "required": [],
    "enforcement": "conditional"
  },
  "extensions": [
    {
      "name": "discount",
      "extends": [
        "$.CheckoutSessionCreateRequest.discounts",
        "$.CheckoutSessionUpdateRequest.discounts",
        "$.CheckoutSession.discounts"
      ]
    }
  ]
}

Payment

handlersPaymentHandler[]

Available payment handlers

{
  "handlers": [
    {
      "id": "card_tokenized",
      "name": "dev.acp.tokenized.card",
      "version": "2026-01-22",
      "spec": "https://acp.dev/handlers/tokenized.card",
      "requires_delegate_payment": true,
      "requires_pci_compliance": false,
      "psp": "stripe",
      "config_schema": "https://acp.dev/schemas/handlers/tokenized.card/config.json",
      "instrument_schemas": [
        "https://acp.dev/schemas/handlers/tokenized.card/instrument.json"
      ],
      "config": {
        "merchant_id": "acct_1234567890"
      }
    }
  ]
}

PaymentHandler

idstring

Seller-defined handler identifier

namestring

Handler name in reverse-DNS format (e.g., dev.acp.tokenized.card)

versionstring

Handler version in YYYY-MM-DD format

specstring

URL to handler specification

requires_delegate_paymentboolean

Whether this handler requires using delegate_payment API

requires_pci_complianceboolean

Whether this handler routes PCI DSS sensitive data

pspstring

Payment Service Provider identifier

config_schemastring

URL to JSON Schema for handler configuration

instrument_schemasstring[]

URLs to JSON Schemas for payment instruments

configobject

Handler-specific configuration

{
  "id": "card_tokenized",
  "name": "dev.acp.tokenized.card",
  "version": "2026-01-22",
  "spec": "https://acp.dev/handlers/tokenized.card",
  "requires_delegate_payment": true,
  "requires_pci_compliance": false,
  "psp": "stripe",
  "config_schema": "https://acp.dev/schemas/handlers/tokenized.card/config.json",
  "instrument_schemas": [
    "https://acp.dev/schemas/handlers/tokenized.card/instrument.json"
  ],
  "config": {
    "merchant_id": "acct_1234567890",
    "accepted_brands": ["visa", "mastercard", "amex", "discover"],
    "accepted_funding_types": ["credit", "debit"],
    "supports_3ds": true,
    "3ds_versions": ["2.1.0", "2.2.0"],
    "environment": "production"
  }
}

InterventionCapabilities

supportedstring[]

Intervention types supported. Agent request: Interventions the agent can handle. Seller response: Intersection of supported interventions. Values: 3ds, biometric, address_verification

requiredstring[]

Intervention methods required for this session (seller only). Values: 3ds, biometric

enforcementstring

Enforcement level (seller only). One of: always, conditional, optional

display_contextstring

How the Agent presents interventions (agent only). One of: native, webview, modal, redirect

redirect_contextstring

How the Agent handles redirects (agent only). One of: in_app, external_browser, none

max_redirectsinteger

Maximum number of redirects the Agent can handle (agent only)

max_interaction_depthinteger

Maximum depth of nested interactions the Agent can handle (agent only)

{
  "supported": ["3ds", "address_verification"],
  "required": [],
  "enforcement": "conditional"
}

ExtensionDeclaration

namestring

Unique identifier for the extension

extendsstring[]

JSONPath expressions identifying the schema fields added by this extension

schemastring

URL to the extension's JSON Schema definition

specstring

URL to the extension's specification document

{
  "name": "discount",
  "extends": [
    "$.CheckoutSessionCreateRequest.discounts",
    "$.CheckoutSessionUpdateRequest.discounts",
    "$.CheckoutSession.discounts"
  ],
  "schema": "https://acp.dev/schemas/discount.json",
  "spec": "https://acp.dev/extensions/discount"
}

Discount Extension

The Discount Extension (dev.acp.discount) enables rich discount code support with detailed applied discount information and line-item allocations.

Discounts

codesstring[]

Discount codes to apply. Case-insensitive. Replaces previously submitted codes. Send empty array to clear.

appliedAppliedDiscount[]

Discounts successfully applied (code-based and automatic)

rejectedRejectedDiscount[]

Discount codes that could not be applied, with reasons

{
  "codes": ["SUMMER25"],
  "applied": [
    {
      "id": "discount_123",
      "code": "SUMMER25",
      "coupon": {
        "id": "coupon_abc123",
        "name": "Summer Sale 20% Off",
        "percent_off": 20.0
      },
      "amount": 2000,
      "automatic": false,
      "allocations": [
        {
          "path": "$.line_items[0]",
          "amount": 2000
        }
      ]
    }
  ],
  "rejected": []
}

AppliedDiscount

idstring

Unique identifier for this applied discount instance

codestring

The discount code entered by the user. Omitted for automatic discounts.

couponCoupon

Details about the underlying coupon/promotion

amountinteger

Total discount amount in minor (cents) currency units

automaticboolean

True if applied automatically by merchant rules (no code required)

startstring

RFC 3339 timestamp when the discount became active

endstring

RFC 3339 timestamp when the discount expires

methodstring

Allocation method. One of: each, across

priorityinteger

Stacking order for discount calculation. Lower numbers applied first (1 = first)

allocationsDiscountAllocation[]

Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount.

{
  "id": "discount_123",
  "code": "SUMMER25",
  "coupon": {
    "id": "coupon_abc123",
    "name": "25% Summer Sale",
    "percent_off": 25.0
  },
  "amount": 2500,
  "automatic": false,
  "method": "each",
  "priority": 1,
  "allocations": [
    {
      "path": "$.line_items[0]",
      "amount": 2500
    }
  ]
}

Coupon

idstring

Unique identifier for the coupon

namestring

Human-readable coupon name (e.g., 'Summer Sale 20% Off')

percent_offnumber

Percentage discount (0-100). Mutually exclusive with amount_off.

amount_offinteger

Fixed discount amount in minor currency units. Mutually exclusive with percent_off.

currencystring

ISO 4217 currency code for amount_off. Required if amount_off is set.

durationstring

How long the discount applies. One of: once, repeating, forever

duration_in_monthsinteger

Number of months the coupon applies if duration is 'repeating'

max_redemptionsinteger

Maximum number of times this coupon can be redeemed across all customers

times_redeemedinteger

Number of times this coupon has been redeemed

metadataobject

Arbitrary key-value metadata attached to the coupon

{
  "id": "coupon_abc123",
  "name": "Summer Sale 20% Off",
  "percent_off": 20.0,
  "duration": "once",
  "max_redemptions": 1000,
  "times_redeemed": 523
}

DiscountAllocation

pathstring

JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping')

amountinteger

Amount allocated to this target in minor (cents) currency units

{
  "path": "$.line_items[0]",
  "amount": 2500
}

RejectedDiscount

codestring

The discount code that was rejected

reasonstring

One of: discount_code_expired, discount_code_invalid, discount_code_already_applied, discount_code_combination_disallowed, discount_code_minimum_not_met, discount_code_user_not_logged_in, discount_code_user_ineligible, discount_code_usage_limit_reached

messagestring

Human-readable explanation

{
  "code": "EXPIRED10",
  "reason": "discount_code_expired",
  "message": "This discount code expired on January 1, 2026"
}

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."
}

Link

typestring

One of: terms_of_use, privacy_policy, return_policy

urlstring

URI

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

PaymentData

handler_idstring

ID of the payment handler to use

instrument.typestring

Instrument type (e.g., card, wallet_token)

instrument.credential.typestring

Credential type (e.g., spt, wallet_token)

instrument.credential.tokenstring

Credential token value

billing_addressAddress

Billing address

purchase_order_numberstring

Purchase order number for B2B payments

payment_termsstring

Payment terms. One of: immediate, net_15, net_30, net_60, net_90

due_datestring

Due date for payment (ISO 8601 date-time)

approval_requiredboolean

Whether approval is required for this payment

{
  "handler_id": "card_tokenized",
  "instrument": {
    "type": "card",
    "credential": {
      "type": "spt",
      "token": "spt_1234567890"
    }
  },
  "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

capabilitiesCapabilities

Supported capabilities including payment handlers, interventions, and extensions

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": "[email protected]"
  },
  "capabilities": {
    "payment": {
      "handlers": [
        {
          "id": "card_tokenized",
          "name": "dev.acp.tokenized.card",
          "version": "2026-01-22",
          "spec": "https://acp.dev/handlers/tokenized.card",
          "requires_delegate_payment": true,
          "requires_pci_compliance": false,
          "psp": "stripe",
          "config_schema": "https://acp.dev/schemas/handlers/tokenized.card/config.json",
          "instrument_schemas": [
            "https://acp.dev/schemas/handlers/tokenized.card/instrument.json"
          ],
          "config": {
            "merchant_id": "acct_1234567890",
            "accepted_brands": ["visa", "mastercard", "amex", "discover"]
          }
        }
      ]
    }
  },
  "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": "[email protected]"
  },
  "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"
}