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., 2026-01-30)

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.

Buyer
buyer
Buyer information including first name, last name, email, and optional phone number.
requiredItem[]
items
Array of items to add to the checkout. Must include at least 1 item. Each item contains an id and quantity.
Address
fulfillment_address
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.

requiredstring
checkout_session_id
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.

requiredstring
checkout_session_id
The unique identifier for the checkout session.
Buyer
buyer
Updated buyer information.
Item[]
items
Updated array of items. This replaces the entire items list.
Address
fulfillment_address
Updated shipping address.
string
fulfillment_option_id
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.

requiredstring
checkout_session_id
The unique identifier for the checkout session.
Buyer
buyer
Updated buyer information if needed.
requiredPaymentData
payment_data
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.

requiredstring
checkout_session_id
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 data models used in the Checkout API.

Address

requiredstring
name
Recipient name for this address
requiredstring
line_one
Primary street address line
string
line_two
Secondary address line (apartment, suite, etc.)
requiredstring
city
City name
requiredstring
state
State or province code
requiredstring
country
ISO 3166-1 alpha-2 country code
requiredstring
postal_code
Postal or ZIP code

{
  "name": "Jane Doe",
  "line_one": "123 Main Street",
  "line_two": "Apt 4B",
  "city": "New York",
  "state": "NY",
  "country": "US",
  "postal_code": "10001"
}

AffiliateAttributionSource

Context about where the attribution originated.

requiredenumstring
type
The type of attribution source.
Possible values
url
platform
unknown
string
url
Canonical content URL when type is 'url'.

{
  "type": "url",
  "url": "https://example.com/product-review"
}

AffiliateAttributionMetadata

Flat key/value map for additional non-sensitive context. Keys must be strings; values must be strings, numbers, or booleans. Arrays and nested objects are NOT permitted.

oneof
[key]
Flat key/value map for additional non-sensitive context. Keys must be strings; values must be strings, numbers, or booleans. Arrays and nested objects are NOT permitted.
Possible types
string
number
boolean

{
  "campaign_type": "influencer",
  "commission_rate": 0.15,
  "is_verified": true
}

AffiliateAttribution

Optional affiliate attribution data for crediting third-party publishers. Write-only: not returned in responses. See RFC: Affiliate Attribution.

Forward compatibility: Servers SHOULD ignore unknown fields to support future extensions (per RFC §8.2).

requiredstring
provider
Identifier for the attribution provider / affiliate network namespace (e.g., 'impact.com').
string
token
Opaque provider-issued token for fraud-resistant validation. Treat as secret.
string
publisher_id
Provider-scoped affiliate/publisher identifier. Required if token is omitted.
string
campaign_id
Provider-scoped campaign identifier.
string
creative_id
Provider-scoped creative identifier.
string
sub_id
Provider-scoped sub-tracking identifier.
AffiliateAttributionSource
source
string
issued_at
RFC3339 timestamp when the attribution token was issued.
string
expires_at
RFC3339 timestamp when the attribution token expires.
AffiliateAttributionMetadata
metadata
enumstring
touchpoint
Attribution touchpoint type. Use 'first' when capturing at session creation, 'last' when capturing at completion. Enables multi-touch attribution models.
Possible values
first
last

{
  "provider": "impact.com",
  "token": "atp_01J8Z3WXYZ9ABC",
  "publisher_id": "pub_123",
  "campaign_id": "camp_summer2026",
  "touchpoint": "first",
  "source": {
    "type": "url",
    "url": "https://example.com/product-review"
  },
  "issued_at": "2026-02-11T10:00:00Z",
  "expires_at": "2026-02-11T11:00:00Z"
}

FulfillmentDetails

string
name
Full name for fulfillment contact
string
phone_number
Contact phone number
string
email
Contact email address
Address
address
Fulfillment address

{
  "name": "John Smith",
  "phone_number": "15551234567",
  "email": "john.smith@example.com",
  "address": {
    "name": "John Smith",
    "line_one": "555 Golden Gate Avenue",
    "line_two": "Apt 401",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94102"
  }
}

CompanyInfo

requiredstring
name
Company or organization name
string
tax_id
Business tax identification number
string
department
Department within the organization
string
cost_center
Cost center code for internal accounting

{
  "name": "Acme Corporation",
  "tax_id": "12-3456789",
  "department": "Marketing",
  "cost_center": "CC-2001"
}

LoyaltyInfo

string
tier
Loyalty program tier level
integer
points_balance
Current loyalty points balance
string
member_since
RFC 3339 timestamp when the customer joined the loyalty program

{
  "tier": "Gold",
  "points_balance": 5000,
  "member_since": "2024-01-15T09:00:00Z"
}

TaxExemption

requiredstring
certificate_id
Unique identifier for the tax exemption certificate
requiredenumstring
certificate_type
Type of tax exemption certificate
Possible values
resale
exempt_organization
government
arraystring
exempt_regions
List of regions where the exemption applies (e.g., state codes)
string
expires_at
RFC 3339 timestamp when the exemption certificate expires

{
  "certificate_id": "cert_12345",
  "certificate_type": "resale",
  "exempt_regions": [
    "CA",
    "NY",
    "TX"
  ],
  "expires_at": "2027-12-31T23:59:59Z"
}

Buyer

string
first_name
Buyer's first name
string
last_name
Buyer's last name
string
full_name
Buyer's full name
requiredstring
email
Buyer's email address
string
phone_number
Buyer's phone number
string
customer_id
Merchant's internal customer identifier
enumstring
account_type
Type of buyer account
Possible values
guest
registered
business
enumstring
authentication_status
Buyer's authentication status
Possible values
authenticated
guest
requires_signin
CompanyInfo
company
Company information for business buyers
LoyaltyInfo
loyalty
Loyalty program information
TaxExemption
tax_exemption
Tax exemption details

{
  "first_name": "Alice",
  "last_name": "Johnson",
  "email": "alice.johnson@example.com",
  "phone_number": "15559876543",
  "customer_id": "cust_abc123",
  "account_type": "registered",
  "authentication_status": "authenticated"
}

InterventionCapabilities

Intervention capabilities. Context-specific fields: display_context, redirect_context, max_redirects, max_interaction_depth (requests only). required, enforcement (responses only). supported field contains intersection in responses.

arraystring
supported
Intervention types supported. - Agent request: Interventions the agent can handle - Seller response: Intersection of supported interventions
arraystring
required
Intervention methods required for this session (seller only).
enumstring
enforcement
When required interventions are enforced (seller only).
Possible values
always
conditional
optional
enumstring
display_context
How the Agent presents interventions (agent only).
Possible values
native
webview
modal
redirect
enumstring
redirect_context
How the Agent handles redirects (agent only).
Possible values
in_app
external_browser
none
integer
max_redirects
Maximum number of redirects the Agent can handle (agent only).
integer
max_interaction_depth
Maximum depth of nested interactions the Agent can handle (agent only).

{
  "supported": [
    "3ds",
    "address_verification"
  ],
  "display_context": "webview",
  "redirect_context": "in_app",
  "max_redirects": 3,
  "max_interaction_depth": 2
}

Capabilities

Capabilities object used in requests and responses. Context determines the party: requests are from Agents, responses are from Sellers. Seller responses contain the intersection of supported interventions.

Payment
payment
InterventionCapabilities
interventions
oneof
extensions
Extensions supported by the party. Requests: array of extension identifiers. Responses: array of extension declaration objects.
Possible types
arraystring
arrayExtensionDeclaration

{
  "payment": {
    "handlers": [
      {
        "id": "handler_1",
        "name": "dev.acp.tokenized.card",
        "version": "2026-01-30",
        "spec": "https://example.com/handler-spec",
        "requires_delegate_payment": true,
        "requires_pci_compliance": false,
        "psp": "stripe",
        "config_schema": "https://example.com/config-schema",
        "instrument_schemas": [
          "https://example.com/instrument-schema"
        ],
        "config": {}
      }
    ]
  },
  "interventions": {
    "supported": [
      "3ds"
    ]
  },
  "extensions": [
    "discount"
  ]
}

ExtensionDeclaration

Extension declaration in capabilities.extensions (response). Describes an active extension and which schema fields it adds.

requiredstring
name
Unique identifier for the extension.
arraystring
extends
JSONPath expressions identifying the schema fields added by this extension. Format: $.<SchemaName>.<fieldName> (e.g., $.CheckoutSession.discounts).
string
schema
URL to the extension's JSON Schema definition.
string
spec
URL to the extension's specification document.

{
  "name": "discount@2026-01-30",
  "extends": [
    "$.CheckoutSession.discounts",
    "$.CheckoutSessionCreateRequest.discounts"
  ],
  "schema": "https://example.com/extensions/discount/schema.json",
  "spec": "https://example.com/extensions/discount/spec"
}

PaymentMethodObject

Payment method with additional constraints (e.g., card brands, PSP routing)

requiredstring
method
The payment method identifier
arraystring
brands
Specific card brands/networks accepted
arraystring
funding_types
For card methods, funding types accepted
arraystring
providers
Optional PSP routing information

{
  "method": "card",
  "brands": [
    "visa",
    "mastercard",
    "amex"
  ],
  "funding_types": [
    "credit",
    "debit"
  ],
  "providers": [
    "stripe"
  ]
}

Item

requiredstring
id
Unique identifier for the item
string
name
Display name of the item
integer
unit_amount
Price per unit in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100)

{
  "id": "item_123",
  "name": "Wireless Headphones",
  "unit_amount": 7999
}

Disclosure

requiredenumstring
type
Type of disclosure
Possible values
disclaimer
requiredenumstring
content_type
Format of the disclosure content
Possible values
plain
markdown
requiredstring
content
The disclosure text content

{
  "type": "disclaimer",
  "content_type": "plain",
  "content": "This product contains small parts and is not suitable for children under 3 years."
}

CustomAttribute

requiredstring
display_name
Human-readable label for the attribute
requiredstring
value
Attribute value

{
  "display_name": "Engraving",
  "value": "Happy Birthday!"
}

MarketplaceSellerDetails

requiredstring
name
Name of the marketplace seller or vendor

{
  "name": "TechGear Store"
}

PaymentHandler

Payment handler configuration and capabilities

requiredstring
id
Seller-defined handler identifier
requiredstring
name
Handler name in reverse-DNS format (e.g., dev.acp.tokenized.card)
requiredstring
version
Handler version in YYYY-MM-DD format
requiredstring
spec
URL to handler specification
requiredboolean
requires_delegate_payment
Whether this handler requires using delegate_payment API
requiredboolean
requires_pci_compliance
Whether this handler routes PCI DSS sensitive data
requiredstring
psp
Payment Service Provider identifier
requiredstring
config_schema
URL to JSON Schema for handler configuration
requiredarraystring
instrument_schemas
URLs to JSON Schemas for payment instruments
requiredobject
config
Handler-specific configuration

{
  "id": "handler_stripe_card",
  "name": "dev.acp.tokenized.card",
  "version": "2026-01-30",
  "spec": "https://example.com/payment-handlers/tokenized-card",
  "requires_delegate_payment": true,
  "requires_pci_compliance": false,
  "psp": "stripe",
  "config_schema": "https://example.com/schemas/card-config.json",
  "instrument_schemas": [
    "https://example.com/schemas/card-instrument.json"
  ],
  "config": {
    "publishable_key": "pk_test_123"
  }
}

Payment

Payment configuration with handlers

requiredarrayPaymentHandler
handlers
Available payment handlers

{
  "handlers": [
    {
      "id": "handler_stripe_card",
      "name": "dev.acp.tokenized.card",
      "version": "2026-01-30",
      "spec": "https://example.com/payment-handlers/tokenized-card",
      "requires_delegate_payment": true,
      "requires_pci_compliance": false,
      "psp": "stripe",
      "config_schema": "https://example.com/schemas/card-config.json",
      "instrument_schemas": [
        "https://example.com/schemas/card-instrument.json"
      ],
      "config": {
        "publishable_key": "pk_test_123"
      }
    }
  ]
}

VariantOption

requiredstring
name
Variant attribute name (e.g., 'Size', 'Color')
requiredstring
value
Variant attribute value (e.g., 'Large', 'Blue')

{
  "name": "Color",
  "value": "Midnight Blue"
}

WeightInfo

requirednumber
value
Numeric weight value
requiredenumstring
unit
Unit of measurement for weight
Possible values
g
kg
oz
lb

{
  "value": 250,
  "unit": "g"
}

DimensionsInfo

requirednumber
length
Length dimension
requirednumber
width
Width dimension
requirednumber
height
Height dimension
requiredenumstring
unit
Unit of measurement for dimensions
Possible values
cm
in

{
  "length": 15.5,
  "width": 10.2,
  "height": 5.8,
  "unit": "cm"
}

DiscountDetail

string
code
Discount code if applicable
requiredenumstring
type
Type of discount
Possible values
percentage
fixed
bogo
volume
requiredinteger
amount
Discount amount in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100)
string
description
Human-readable discount description
enumstring
source
Source of the discount
Possible values
coupon
automatic
loyalty

{
  "code": "SAVE20",
  "type": "percentage",
  "amount": 1600,
  "description": "20% off your order",
  "source": "coupon"
}

LineItem

requiredstring
id
Unique identifier for the line item
requiredItem
item
Reference to the item being purchased
requiredinteger
quantity
Number of units for this line item
string
name
Display name of the line item
string
description
Detailed description of the line item
arraystring
images
Array of image URLs for this line item
integer
unit_amount
Price per unit in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100)
arrayDisclosure
disclosures
Legal disclosures or disclaimers for this item
arrayCustomAttribute
custom_attributes
Custom attributes specific to this line item
MarketplaceSellerDetails
marketplace_seller_details
Seller details for marketplace items
string
product_id
Merchant's product identifier
string
sku
Stock keeping unit identifier
string
variant_id
Product variant identifier
string
category
Product category
arraystring
tags
Product tags or labels
WeightInfo
weight
Weight information for the item
DimensionsInfo
dimensions
Dimensions for the item
enumstring
availability_status
Current availability status of the item
Possible values
in_stock
low_stock
out_of_stock
backorder
pre_order
integer
available_quantity
Quantity currently available for purchase
integer
max_quantity_per_order
Maximum quantity allowed per order
string
fulfillable_on
RFC 3339 timestamp when item becomes available for fulfillment
arrayVariantOption
variant_options
Selected product variant options (e.g., size, color)
arrayDiscountDetail
discount_details
Line-item level discount details
boolean
tax_exempt
Whether this line item is tax exempt
string
tax_exemption_reason
Reason for tax exemption if applicable
string
parent_id
Reference to parent line item for bundled products
requiredarrayTotal
totals
Line-item level totals breakdown including base_amount, discount, subtotal, tax, and total

{
  "id": "li_001",
  "item": {
    "id": "item_123",
    "name": "Wireless Headphones",
    "unit_amount": 7999
  },
  "quantity": 2,
  "name": "Premium Wireless Headphones",
  "unit_amount": 7999,
  "availability_status": "in_stock",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 15998
    }
  ]
}

TaxBreakdownItem

requiredstring
jurisdiction
Tax jurisdiction name (e.g., 'California State Tax', 'City of San Francisco')
requirednumber
rate
Tax rate as a decimal (e.g., 0.0875 for 8.75%)
requiredinteger
amount
Tax amount in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100)

{
  "jurisdiction": "California State Tax",
  "rate": 0.0725,
  "amount": 1160
}

Total

requiredenumstring
type
Type of total line item
Possible values
items_base_amount
items_discount
subtotal
discount
fulfillment
tax
fee
gift_wrap
tip
store_credit
total
requiredstring
display_text
Localized display text for this total
requiredinteger
amount
Amount in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100)
integer
presentment_amount
Amount in presentment currency minor units if different from settlement currency
string
description
Additional descriptive text for this total
arrayTaxBreakdownItem
breakdown
Detailed breakdown for tax totals

{
  "type": "tax",
  "display_text": "Sales Tax",
  "amount": 1400,
  "breakdown": [
    {
      "jurisdiction": "California State Tax",
      "rate": 0.0725,
      "amount": 1160
    },
    {
      "jurisdiction": "San Francisco County Tax",
      "rate": 0.015,
      "amount": 240
    }
  ]
}

FulfillmentOptionPickup

requiredstring
type
Fulfillment type discriminator
requiredstring
id
Unique identifier for this fulfillment option
requiredstring
title
Display title for this pickup option
string
description
Additional details about this pickup option
requiredobject
location
Pickup location details
enumstring
pickup_type
Type of pickup method
Possible values
in_store
curbside
locker
string
ready_by
RFC 3339 timestamp when order will be ready for pickup
string
pickup_by
RFC 3339 timestamp by which order must be picked up
requiredarrayTotal
totals
Cost breakdown for this fulfillment option

{
  "type": "pickup",
  "id": "pickup_001",
  "title": "In-Store Pickup",
  "description": "Pick up at our downtown location",
  "location": {
    "name": "Downtown Store",
    "address": {
      "name": "Downtown Store",
      "line_one": "100 Market Street",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94105"
    },
    "phone": "14155551234",
    "instructions": "Use the pickup counter on the first floor"
  },
  "pickup_type": "in_store",
  "ready_by": "2026-02-12T15:00:00Z",
  "totals": [
    {
      "type": "fulfillment",
      "display_text": "Pickup",
      "amount": 0
    }
  ]
}

FulfillmentOptionLocalDelivery

requiredstring
type
Fulfillment type discriminator
requiredstring
id
Unique identifier for this fulfillment option
requiredstring
title
Display title for this local delivery option
string
description
Additional details about this delivery option
object
delivery_window
Expected delivery time window
object
service_area
Geographic service area for local delivery
requiredarrayTotal
totals
Cost breakdown for this fulfillment option

{
  "type": "local_delivery",
  "id": "local_001",
  "title": "Same-Day Local Delivery",
  "description": "Delivered by our team today",
  "delivery_window": {
    "start": "2026-02-11T16:00:00Z",
    "end": "2026-02-11T20:00:00Z"
  },
  "service_area": {
    "radius_miles": 10,
    "center_postal_code": "94102"
  },
  "totals": [
    {
      "type": "fulfillment",
      "display_text": "Delivery Fee",
      "amount": 999
    }
  ]
}

FulfillmentOptionShipping

requiredstring
type
Fulfillment type discriminator
requiredstring
id
Unique identifier for this fulfillment option
requiredstring
title
Display title for this shipping option (e.g., 'Standard Shipping', 'Express')
string
description
Additional details about this shipping option
string
carrier
Shipping carrier name (e.g., 'USPS', 'FedEx')
string
earliest_delivery_time
RFC 3339 timestamp for earliest expected delivery
string
latest_delivery_time
RFC 3339 timestamp for latest expected delivery
requiredarrayTotal
totals
Cost breakdown for this fulfillment option

{
  "type": "shipping",
  "id": "ship_standard",
  "title": "Standard Shipping",
  "description": "Delivery in 5-7 business days",
  "carrier": "USPS",
  "earliest_delivery_time": "2026-02-16T00:00:00Z",
  "latest_delivery_time": "2026-02-20T23:59:59Z",
  "totals": [
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 599
    }
  ]
}

FulfillmentOptionDigital

requiredstring
type
Fulfillment type discriminator
requiredstring
id
Unique identifier for this fulfillment option
requiredstring
title
Display title for this digital delivery option
string
description
Additional details about digital delivery method
requiredarrayTotal
totals
Cost breakdown for this fulfillment option

{
  "type": "digital",
  "id": "digital_001",
  "title": "Instant Download",
  "description": "Available immediately after purchase",
  "totals": [
    {
      "type": "fulfillment",
      "display_text": "Digital Delivery",
      "amount": 0
    }
  ]
}

SelectedFulfillmentOption

requiredenumstring
type
Type of fulfillment option selected
Possible values
shipping
digital
pickup
local_delivery
requiredstring
option_id
ID of the selected fulfillment option
requiredarraystring
item_ids
List of line item IDs associated with this fulfillment option

{
  "type": "shipping",
  "option_id": "ship_standard",
  "item_ids": [
    "li_001",
    "li_002"
  ]
}

MessageInfo

requiredstring
type
Message type discriminator
enumstring
severity
Severity level of this informational message
Possible values
info
low
medium
high
critical
string
param
RFC 9535 JSONPath to the related field
requiredenumstring
content_type
Format of the message content
Possible values
plain
markdown
requiredstring
content
Informational message text

{
  "type": "info",
  "severity": "info",
  "content_type": "plain",
  "content": "Free shipping on orders over $50"
}

MessageWarning

requiredstring
type
Message type discriminator
requiredenumstring
code
Warning code indicating the type of warning
Possible values
low_stock
high_demand
shipping_delay
price_change
expiring_promotion
limited_availability
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
enumstring
severity
Severity level of this warning
Possible values
info
low
medium
high
critical
string
param
RFC 9535 JSONPath to the related field
requiredenumstring
content_type
Format of the warning message content
Possible values
plain
markdown
requiredstring
content
Warning message text

{
  "type": "warning",
  "code": "low_stock",
  "severity": "medium",
  "param": "$.line_items[0]",
  "content_type": "plain",
  "content": "Only 3 items left in stock"
}

MessageError

Business-logic error within a valid CheckoutSession response. Used in messages[] on 2xx responses when the session is valid but has actionable issues (e.g. status "not_ready_for_payment"). The agent can respond by asking the buyer for corrections or trying alternatives. Use MessageError—not Error—when you can return a valid CheckoutSession and the problem is conversational (e.g. invalid email → code "invalid" and param "$.buyer.email"; out of stock → code "out_of_stock" and param "$.items[0]").

requiredstring
type
Message type discriminator
requiredenumstring
code
Error code indicating the type of error
Possible values
missing
invalid
out_of_stock
payment_declined
requires_sign_in
requires_3ds
low_stock
quantity_exceeded
coupon_invalid
coupon_expired
minimum_not_met
maximum_exceeded
region_restricted
age_verification_required
approval_required
unsupported
not_found
conflict
rate_limited
expired
intervention_required
enumstring
severity
Severity level of this error
Possible values
info
low
medium
high
critical
string
param
RFC 9535 JSONPath
requiredenumstring
content_type
Format of the error message content
Possible values
plain
markdown
requiredstring
content
Error message text

{
  "type": "error",
  "code": "out_of_stock",
  "severity": "medium",
  "param": "$.line_items[0]",
  "content_type": "plain",
  "content": "The item is out of stock"
}

GiftWrap

requiredboolean
enabled
Whether gift wrapping is enabled for this order
enumstring
style
Gift wrap style selected
Possible values
birthday
holiday
elegant
integer
charge
Additional charge for gift wrapping in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100)

{
  "enabled": true,
  "style": "elegant",
  "charge": 500
}

requiredenumstring
type
Type of link
Possible values
terms_of_use
privacy_policy
return_policy
shipping_policy
contact_us
about_us
faq
support
string
title
Display text for the link
requiredstring
url
URL destination

{
  "type": "return_policy",
  "title": "Return Policy",
  "url": "https://example.com/returns"
}

SplitPayment

requiredinteger
amount
Payment amount in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100) for this split

{
  "amount": 5000
}

PaymentData

string
handler_id
ID of the payment handler to use
object
instrument
Payment instrument details
Address
billing_address
Billing address for the payment
string
purchase_order_number
Purchase order number
enumstring
payment_terms
Payment terms for B2B transactions
Possible values
immediate
net_15
net_30
net_60
net_90
string
due_date
RFC 3339 timestamp when payment is due
boolean
approval_required
Whether this payment requires approval

{
  "handler_id": "handler_stripe_card",
  "instrument": {
    "type": "card",
    "credential": {
      "type": "spt",
      "token": "spt_1234567890"
    }
  },
  "billing_address": {
    "name": "John Smith",
    "line_one": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postal_code": "10001"
  }
}

FulfillmentGroup

requiredstring
id
Unique identifier for this fulfillment group
requiredarraystring
item_ids
List of line item IDs in this fulfillment group
requiredenumstring
destination_type
Type of fulfillment for this group
Possible values
shipping
pickup
local_delivery
digital
FulfillmentDetails
fulfillment_details
Fulfillment contact and address details
string
location_id
Location identifier for pickup or local delivery
string
instructions
Special fulfillment instructions

{
  "id": "fg_001",
  "item_ids": [
    "li_001",
    "li_002"
  ],
  "destination_type": "shipping",
  "instructions": "Leave package at front door"
}

EstimatedDelivery

requiredstring
earliest
RFC 3339 timestamp for earliest expected delivery
requiredstring
latest
RFC 3339 timestamp for latest expected delivery

{
  "earliest": "2026-02-14T00:00:00Z",
  "latest": "2026-02-18T23:59:59Z"
}

OrderConfirmation

string
confirmation_number
Order confirmation number
boolean
confirmation_email_sent
Whether a confirmation email has been sent
string
receipt_url
URL to the order receipt
string
invoice_number
Invoice number if generated

{
  "confirmation_number": "ORD-2026-02-11-001",
  "confirmation_email_sent": true,
  "receipt_url": "https://example.com/receipts/ord_123",
  "invoice_number": "INV-2026-001"
}

SupportInfo

string
email
Support contact email
string
phone
Support contact phone number
string
hours
Support hours of operation
string
help_center_url
URL to merchant's help center

{
  "email": "support@example.com",
  "phone": "18005551234",
  "hours": "Mon-Fri 9am-5pm PST",
  "help_center_url": "https://example.com/help"
}

Order

requiredstring
id
Unique identifier for the order
requiredstring
checkout_session_id
ID of the checkout session that created this order
string
order_number
Human-readable order number
requiredstring
permalink_url
Permanent URL where the customer can view order details
enumstring
status
Current order status
Possible values
confirmed
processing
shipped
delivered
EstimatedDelivery
estimated_delivery
Estimated delivery time range
OrderConfirmation
confirmation
Order confirmation details
SupportInfo
support
Customer support contact information

{
  "id": "ord_123456",
  "checkout_session_id": "cs_abc123",
  "order_number": "ORD-2026-001",
  "permalink_url": "https://example.com/orders/ord_123456",
  "status": "confirmed",
  "estimated_delivery": {
    "earliest": "2026-02-14T00:00:00Z",
    "latest": "2026-02-18T23:59:59Z"
  },
  "confirmation": {
    "confirmation_number": "ORD-2026-02-11-001",
    "confirmation_email_sent": true,
    "receipt_url": "https://example.com/receipts/ord_123456"
  }
}

ProtocolVersion

Protocol metadata included in checkout responses. Indicates the ACP version.

requiredstring
version
ACP protocol version in YYYY-MM-DD format.

{
  "version": "2026-01-30"
}

DiscountAllocation

Breakdown of how a discount amount was allocated to a specific target.

requiredstring
path
JSONPath to the allocation target (e.g., '$.line_items[0]', '$.totals.shipping').
requiredinteger
amount
Amount allocated to this target in minor (cents) currency units.

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

Coupon

Coupon details describing the discount terms.

requiredstring
id
Unique identifier for the coupon.
requiredstring
name
Human-readable coupon name (e.g., 'Summer Sale 20% Off').
number
percent_off
Percentage discount (0-100). Mutually exclusive with amount_off.
integer
amount_off
Fixed discount amount in minor currency units. Mutually exclusive with percent_off.
string
currency
ISO 4217 currency code for amount_off. Required if amount_off is set.
enumstring
duration
How long the discount applies. 'once' = single use, 'repeating' = multiple billing periods, 'forever' = indefinitely.
Possible values
once
repeating
forever
integer
duration_in_months
Number of months the coupon applies if duration is 'repeating'.
integer
max_redemptions
Maximum number of times this coupon can be redeemed across all customers.
integer
times_redeemed
Number of times this coupon has been redeemed.
object
metadata
Arbitrary key-value metadata attached to the coupon.

{
  "id": "coupon_summer2026",
  "name": "Summer Sale 20% Off",
  "percent_off": 20,
  "duration": "once",
  "max_redemptions": 1000,
  "times_redeemed": 145
}

AppliedDiscount

A discount that was successfully applied to the checkout session.

requiredstring
id
Unique identifier for this applied discount instance.
string
code
The discount code entered by the user. Omitted for automatic discounts.
requiredCoupon
coupon
requiredinteger
amount
Total discount amount in minor (cents) currency units.
boolean
automatic
True if applied automatically by merchant rules (no code required).
string
start
RFC 3339 timestamp when the discount became active.
string
end
RFC 3339 timestamp when the discount expires.
enumstring
method
Allocation method. 'each' = applied independently per item. 'across' = split proportionally by value.
Possible values
each
across
integer
priority
Stacking order for discount calculation. Lower numbers applied first (1 = first).
arrayDiscountAllocation
allocations
Breakdown of where this discount was allocated. Sum of allocation amounts equals total amount.

{
  "id": "applied_discount_001",
  "code": "SAVE20",
  "coupon": {
    "id": "coupon_summer2026",
    "name": "Summer Sale 20% Off",
    "percent_off": 20,
    "duration": "once"
  },
  "amount": 1600,
  "automatic": false,
  "method": "across",
  "priority": 1,
  "allocations": [
    {
      "path": "$.line_items[0]",
      "amount": 1600
    }
  ]
}

RejectedDiscount

A discount code that could not be applied, with the reason.

requiredstring
code
The discount code that was rejected.
requiredDiscountErrorCode
reason
Error code indicating why the discount was rejected.
string
message
Human-readable explanation of why the code was rejected.

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

DiscountErrorCode

Error codes for rejected discount codes, used in messages[].code.

enumstring
value
Error codes for rejected discount codes, used in messages[].code.
Possible values
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

DiscountsRequest

Discount codes input for checkout create/update requests.

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

{
  "codes": [
    "SAVE20",
    "FREESHIP"
  ]
}

DiscountsResponse

Discount codes input and applied discounts output in checkout responses.

arraystring
codes
Echo of submitted discount codes.
arrayAppliedDiscount
applied
Discounts successfully applied (code-based and automatic).
arrayRejectedDiscount
rejected
Discount codes that could not be applied, with reasons.

{
  "codes": [
    "SAVE20"
  ],
  "applied": [
    {
      "id": "applied_discount_001",
      "code": "SAVE20",
      "coupon": {
        "id": "coupon_summer2026",
        "name": "Summer Sale 20% Off",
        "percent_off": 20,
        "duration": "once"
      },
      "amount": 1600,
      "automatic": false,
      "method": "across"
    }
  ],
  "rejected": []
}

PaymentResponse

string
provider
Payment provider identifier
arrayobject
instruments
Available payment instruments
arrayobject
handlers
Available payment handlers

{
  "provider": "stripe",
  "instruments": [],
  "handlers": []
}

CheckoutSessionBase

requiredstring
id
Unique identifier for the checkout session
ProtocolVersion
protocol
Protocol version metadata
requiredCapabilities
capabilities
Negotiated capabilities between agent and seller
Buyer
buyer
Buyer information
requiredenumstring
status
Current status of the checkout session
Possible values
incomplete
not_ready_for_payment
requires_escalation
authentication_required
ready_for_payment
pending_approval
complete_in_progress
completed
canceled
in_progress
expired
requiredstring
currency
ISO 4217 settlement currency code
string
presentment_currency
ISO 4217 presentment currency code if different from settlement currency
number
exchange_rate
Exchange rate from presentment to settlement currency
string
exchange_rate_timestamp
RFC 3339 timestamp when exchange rate was determined
string
locale
Locale code (e.g., 'en-US') for localizing content
string
timezone
IANA timezone identifier (e.g., 'America/New_York')
requiredarrayLineItem
line_items
Line items in the checkout session
FulfillmentDetails
fulfillment_details
Fulfillment contact and address details
requiredoneof
fulfillment_options
Available fulfillment options
Possible types
FulfillmentOptionShipping
FulfillmentOptionDigital
FulfillmentOptionPickup
FulfillmentOptionLocalDelivery
arraySelectedFulfillmentOption
selected_fulfillment_options
Currently selected fulfillment options
arrayFulfillmentGroup
fulfillment_groups
Grouping of line items by fulfillment method
requiredarrayTotal
totals
Cart-level totals breakdown
requiredoneof
messages
Messages to communicate with the buyer (info, warnings, errors)
Possible types
MessageInfo
MessageWarning
MessageError
requiredarrayLink
links
Relevant links (terms, policies, support)
AuthenticationMetadata
authentication_metadata
Authentication metadata for payment interventions (e.g., 3DS)
string
created_at
RFC 3339 timestamp when the session was created
string
updated_at
RFC 3339 timestamp of last update
string
expires_at
RFC 3339 timestamp when the session expires
string
continue_url
URL to continue or resume the checkout session
object
metadata
Arbitrary metadata for merchant use
string
quote_id
Quote identifier if this session is based on a quote
string
quote_expires_at
RFC 3339 timestamp when the quote expires
DiscountsResponse
discounts
Discount extension: submitted codes and applied discounts. Present when the 'discount' extension is active.

{
  "id": "cs_abc123",
  "protocol": {
    "version": "2026-01-30"
  },
  "capabilities": {
    "payment": {
      "handlers": [
        {
          "id": "handler_stripe_card",
          "name": "dev.acp.tokenized.card",
          "version": "2026-01-30",
          "spec": "https://example.com/payment-handlers/tokenized-card",
          "requires_delegate_payment": true,
          "requires_pci_compliance": false,
          "psp": "stripe",
          "config_schema": "https://example.com/schemas/card-config.json",
          "instrument_schemas": [
            "https://example.com/schemas/card-instrument.json"
          ],
          "config": {}
        }
      ]
    },
    "interventions": {
      "supported": [
        "3ds"
      ]
    },
    "extensions": [
      {
        "name": "discount@2026-01-30",
        "extends": [
          "$.CheckoutSession.discounts"
        ],
        "schema": "https://example.com/extensions/discount/schema.json",
        "spec": "https://example.com/extensions/discount/spec"
      }
    ]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "li_001",
      "item": {
        "id": "item_123",
        "name": "Wireless Headphones",
        "unit_amount": 7999
      },
      "quantity": 2,
      "name": "Premium Wireless Headphones",
      "unit_amount": 7999,
      "availability_status": "in_stock",
      "totals": [
        {
          "type": "subtotal",
          "display_text": "Subtotal",
          "amount": 15998
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 15998
    },
    {
      "type": "tax",
      "display_text": "Sales Tax",
      "amount": 1400
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 17398
    }
  ],
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "ship_standard",
      "title": "Standard Shipping",
      "carrier": "USPS",
      "totals": [
        {
          "type": "fulfillment",
          "display_text": "Shipping",
          "amount": 599
        }
      ]
    }
  ],
  "messages": [],
  "links": [
    {
      "type": "return_policy",
      "title": "Return Policy",
      "url": "https://example.com/returns"
    }
  ],
  "created_at": "2026-02-11T10:00:00Z",
  "updated_at": "2026-02-11T10:05:00Z",
  "expires_at": "2026-02-11T22:00:00Z"
}

CheckoutSession

requiredstring
id
Unique identifier for the checkout session
ProtocolVersion
protocol
Protocol version metadata
requiredCapabilities
capabilities
Negotiated capabilities between agent and seller
Buyer
buyer
Buyer information
requiredenumstring
status
Current status of the checkout session
Possible values
incomplete
not_ready_for_payment
requires_escalation
authentication_required
ready_for_payment
pending_approval
complete_in_progress
completed
canceled
in_progress
expired
requiredstring
currency
ISO 4217 settlement currency code
string
presentment_currency
ISO 4217 presentment currency code if different from settlement currency
number
exchange_rate
Exchange rate from presentment to settlement currency
string
exchange_rate_timestamp
RFC 3339 timestamp when exchange rate was determined
string
locale
Locale code (e.g., 'en-US') for localizing content
string
timezone
IANA timezone identifier (e.g., 'America/New_York')
requiredarrayLineItem
line_items
Line items in the checkout session
FulfillmentDetails
fulfillment_details
Fulfillment contact and address details
requiredoneof
fulfillment_options
Available fulfillment options
Possible types
FulfillmentOptionShipping
FulfillmentOptionDigital
FulfillmentOptionPickup
FulfillmentOptionLocalDelivery
arraySelectedFulfillmentOption
selected_fulfillment_options
Currently selected fulfillment options
arrayFulfillmentGroup
fulfillment_groups
Grouping of line items by fulfillment method
requiredarrayTotal
totals
Cart-level totals breakdown
requiredoneof
messages
Messages to communicate with the buyer (info, warnings, errors)
Possible types
MessageInfo
MessageWarning
MessageError
requiredarrayLink
links
Relevant links (terms, policies, support)
AuthenticationMetadata
authentication_metadata
Authentication metadata for payment interventions (e.g., 3DS)
string
created_at
RFC 3339 timestamp when the session was created
string
updated_at
RFC 3339 timestamp of last update
string
expires_at
RFC 3339 timestamp when the session expires
string
continue_url
URL to continue or resume the checkout session
object
metadata
Arbitrary metadata for merchant use
string
quote_id
Quote identifier if this session is based on a quote
string
quote_expires_at
RFC 3339 timestamp when the quote expires
DiscountsResponse
discounts
Discount extension: submitted codes and applied discounts. Present when the 'discount' extension is active.

{
  "id": "cs_abc123",
  "protocol": {
    "version": "2026-01-30"
  },
  "capabilities": {
    "payment": {
      "handlers": [
        {
          "id": "handler_stripe_card",
          "name": "dev.acp.tokenized.card",
          "version": "2026-01-30",
          "spec": "https://example.com/payment-handlers/tokenized-card",
          "requires_delegate_payment": true,
          "requires_pci_compliance": false,
          "psp": "stripe",
          "config_schema": "https://example.com/schemas/card-config.json",
          "instrument_schemas": [
            "https://example.com/schemas/card-instrument.json"
          ],
          "config": {}
        }
      ]
    },
    "interventions": {
      "supported": [
        "3ds"
      ]
    },
    "extensions": [
      {
        "name": "discount@2026-01-30",
        "extends": [
          "$.CheckoutSession.discounts"
        ],
        "schema": "https://example.com/extensions/discount/schema.json",
        "spec": "https://example.com/extensions/discount/spec"
      }
    ]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "li_001",
      "item": {
        "id": "item_123",
        "name": "Wireless Headphones",
        "unit_amount": 7999
      },
      "quantity": 2,
      "name": "Premium Wireless Headphones",
      "unit_amount": 7999,
      "availability_status": "in_stock",
      "totals": [
        {
          "type": "subtotal",
          "display_text": "Subtotal",
          "amount": 15998
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 15998
    },
    {
      "type": "tax",
      "display_text": "Sales Tax",
      "amount": 1400
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 17398
    }
  ],
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "ship_standard",
      "title": "Standard Shipping",
      "carrier": "USPS",
      "totals": [
        {
          "type": "fulfillment",
          "display_text": "Shipping",
          "amount": 599
        }
      ]
    }
  ],
  "messages": [],
  "links": [
    {
      "type": "return_policy",
      "title": "Return Policy",
      "url": "https://example.com/returns"
    }
  ],
  "created_at": "2026-02-11T10:00:00Z",
  "updated_at": "2026-02-11T10:05:00Z",
  "expires_at": "2026-02-11T22:00:00Z"
}

CheckoutSessionWithOrder

requiredstring
id
Unique identifier for the checkout session
ProtocolVersion
protocol
Protocol version metadata
requiredCapabilities
capabilities
Negotiated capabilities between agent and seller
Buyer
buyer
Buyer information
requiredenumstring
status
Current status of the checkout session
Possible values
incomplete
not_ready_for_payment
requires_escalation
authentication_required
ready_for_payment
pending_approval
complete_in_progress
completed
canceled
in_progress
expired
requiredstring
currency
ISO 4217 settlement currency code
string
presentment_currency
ISO 4217 presentment currency code if different from settlement currency
number
exchange_rate
Exchange rate from presentment to settlement currency
string
exchange_rate_timestamp
RFC 3339 timestamp when exchange rate was determined
string
locale
Locale code (e.g., 'en-US') for localizing content
string
timezone
IANA timezone identifier (e.g., 'America/New_York')
requiredarrayLineItem
line_items
Line items in the checkout session
FulfillmentDetails
fulfillment_details
Fulfillment contact and address details
requiredoneof
fulfillment_options
Available fulfillment options
Possible types
FulfillmentOptionShipping
FulfillmentOptionDigital
FulfillmentOptionPickup
FulfillmentOptionLocalDelivery
arraySelectedFulfillmentOption
selected_fulfillment_options
Currently selected fulfillment options
arrayFulfillmentGroup
fulfillment_groups
Grouping of line items by fulfillment method
requiredarrayTotal
totals
Cart-level totals breakdown
requiredoneof
messages
Messages to communicate with the buyer (info, warnings, errors)
Possible types
MessageInfo
MessageWarning
MessageError
requiredarrayLink
links
Relevant links (terms, policies, support)
AuthenticationMetadata
authentication_metadata
Authentication metadata for payment interventions (e.g., 3DS)
string
created_at
RFC 3339 timestamp when the session was created
string
updated_at
RFC 3339 timestamp of last update
string
expires_at
RFC 3339 timestamp when the session expires
string
continue_url
URL to continue or resume the checkout session
object
metadata
Arbitrary metadata for merchant use
string
quote_id
Quote identifier if this session is based on a quote
string
quote_expires_at
RFC 3339 timestamp when the quote expires
DiscountsResponse
discounts
Discount extension: submitted codes and applied discounts. Present when the 'discount' extension is active.
requiredOrder
order

{
  "id": "cs_abc123",
  "protocol": {
    "version": "2026-01-30"
  },
  "capabilities": {
    "payment": {
      "handlers": [
        {
          "id": "handler_stripe_card",
          "name": "dev.acp.tokenized.card",
          "version": "2026-01-30",
          "spec": "https://example.com/payment-handlers/tokenized-card",
          "requires_delegate_payment": true,
          "requires_pci_compliance": false,
          "psp": "stripe",
          "config_schema": "https://example.com/schemas/card-config.json",
          "instrument_schemas": [
            "https://example.com/schemas/card-instrument.json"
          ],
          "config": {}
        }
      ]
    },
    "interventions": {
      "supported": [
        "3ds"
      ]
    },
    "extensions": [
      {
        "name": "discount@2026-01-30",
        "extends": [
          "$.CheckoutSession.discounts"
        ],
        "schema": "https://example.com/extensions/discount/schema.json",
        "spec": "https://example.com/extensions/discount/spec"
      }
    ]
  },
  "status": "completed",
  "currency": "usd",
  "line_items": [
    {
      "id": "li_001",
      "item": {
        "id": "item_123",
        "name": "Wireless Headphones",
        "unit_amount": 7999
      },
      "quantity": 2,
      "name": "Premium Wireless Headphones",
      "unit_amount": 7999,
      "availability_status": "in_stock",
      "totals": [
        {
          "type": "subtotal",
          "display_text": "Subtotal",
          "amount": 15998
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 15998
    },
    {
      "type": "tax",
      "display_text": "Sales Tax",
      "amount": 1400
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 17398
    }
  ],
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "ship_standard",
      "title": "Standard Shipping",
      "carrier": "USPS",
      "totals": [
        {
          "type": "fulfillment",
          "display_text": "Shipping",
          "amount": 599
        }
      ]
    }
  ],
  "messages": [],
  "links": [
    {
      "type": "return_policy",
      "title": "Return Policy",
      "url": "https://example.com/returns"
    }
  ],
  "created_at": "2026-02-11T10:00:00Z",
  "updated_at": "2026-02-11T10:30:00Z",
  "order": {
    "id": "ord_123456",
    "checkout_session_id": "cs_abc123",
    "order_number": "ORD-2026-001",
    "permalink_url": "https://example.com/orders/ord_123456",
    "status": "confirmed"
  }
}

CheckoutSessionCreateRequest

Buyer
buyer
Buyer information
requiredarrayItem
line_items
Items to add to the checkout session
requiredstring
currency
ISO 4217 currency code
FulfillmentDetails
fulfillment_details
Fulfillment contact and address details
requiredCapabilities
capabilities
Agent capabilities and supported features
arrayFulfillmentGroup
fulfillment_groups
Grouping of items by fulfillment method
AffiliateAttribution
affiliate_attribution
Affiliate attribution data for first-touch tracking
arraystring
coupons
DEPRECATED: Use discounts.codes instead. Discount codes to apply.
DiscountsRequest
discounts
Discount codes to apply to the checkout session.
string
locale
Locale code for localizing content (e.g., 'en-US')
string
timezone
IANA timezone identifier (e.g., 'America/New_York')
string
quote_id
Quote identifier if this session is based on a quote
object
metadata
Arbitrary metadata for merchant use

{
  "line_items": [
    {
      "id": "item_123",
      "name": "Wireless Headphones",
      "unit_amount": 7999
    }
  ],
  "currency": "usd",
  "capabilities": {
    "payment": {
      "handlers": [
        {
          "id": "handler_stripe_card",
          "name": "dev.acp.tokenized.card",
          "version": "2026-01-30",
          "spec": "https://example.com/payment-handlers/tokenized-card",
          "requires_delegate_payment": true,
          "requires_pci_compliance": false,
          "psp": "stripe",
          "config_schema": "https://example.com/schemas/card-config.json",
          "instrument_schemas": [
            "https://example.com/schemas/card-instrument.json"
          ],
          "config": {}
        }
      ]
    },
    "interventions": {
      "supported": [
        "3ds"
      ]
    },
    "extensions": [
      "discount"
    ]
  }
}

CheckoutSessionUpdateRequest

Buyer
buyer
Updated buyer information
arrayItem
line_items
Items to update in the checkout session
FulfillmentDetails
fulfillment_details
Updated fulfillment contact and address
arrayFulfillmentGroup
fulfillment_groups
Updated fulfillment groupings
arraySelectedFulfillmentOption
selected_fulfillment_options
Fulfillment option selected by the buyer
arraystring
coupons
DEPRECATED: Use discounts.codes instead. Discount codes to apply.
DiscountsRequest
discounts
Discount codes to apply. Replaces previously submitted codes.

{
  "selected_fulfillment_options": [
    {
      "type": "shipping",
      "option_id": "ship_standard",
      "item_ids": [
        "li_001"
      ]
    }
  ]
}

RiskSignals

string
ip_address
IP address of the buyer
string
user_agent
User agent string of the buyer's browser
string
accept_language
Accept-Language header from the buyer's browser
string
session_id
Session identifier for the buyer
string
device_fingerprint
Device fingerprint for fraud detection

{
  "ip_address": "203.0.113.45",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
  "accept_language": "en-US,en;q=0.9",
  "session_id": "sess_abc123",
  "device_fingerprint": "fp_xyz789"
}

CheckoutSessionCompleteRequest

Buyer
buyer
Final buyer information
requiredPaymentData
payment_data
Payment method and details
AuthenticationResult
authentication_result
Authentication result for 3DS flows
AffiliateAttribution
affiliate_attribution
Affiliate attribution data for last-touch tracking
RiskSignals
risk_signals
Risk and fraud signals

{
  "buyer": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "johnsmith@mail.com"
  },
  "payment_data": {
    "handler_id": "handler_stripe_card",
    "instrument": {
      "type": "card",
      "credential": {
        "type": "spt",
        "token": "spt_123"
      }
    }
  }
}

AuthenticationMetadata

Seller-provided authentication metadata for 3DS flows.

requiredobject
channel
Details about the channel used for this 3DS Authentication.
requiredobject
acquirer_details
Details about the acquirer used for this 3DS Authentication. This object MUST be present.
requiredenumstring
directory_server
The 3DS directory server used for this Authentication.
Possible values
american_express
mastercard
visa
object
flow_preference
Contains additional details on the seller's preference for the 3DS authentication flow. Sellers MAY request a preference, but issuers ultimately decide the actual flow.

{
  "channel": {
    "type": "browser",
    "browser": {
      "accept_header": "text/html,application/xhtml+xml",
      "ip_address": "203.0.113.45",
      "javascript_enabled": true,
      "language": "en-US",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "color_depth": 24,
      "java_enabled": false,
      "screen_height": 1080,
      "screen_width": 1920,
      "timezone_offset": -480
    }
  },
  "acquirer_details": {
    "acquirer_bin": "123456",
    "acquirer_country": "US",
    "acquirer_merchant_id": "merchant_123",
    "merchant_name": "Example Store"
  },
  "directory_server": "visa"
}

AuthenticationResult

Agent-provided authentication results returned to the seller for card-based 3D Secure.

requiredenumstring
outcome
The outcome of this 3DS Authentication.
Possible values
abandoned
attempt_acknowledged
authenticated
canceled
denied
informational
internal_error
not_supported
processing_error
rejected
object
outcome_details
Detailed authentication data. This field is required when the outcome is 'authenticated', 'informational', or 'attempt_acknowledged'.

{
  "outcome": "authenticated",
  "outcome_details": {
    "three_ds_cryptogram": "AbCdEfGhIjKlMnOpQrStUvWxY0=",
    "electronic_commerce_indicator": "05",
    "transaction_id": "dsTransId_abc123",
    "version": "2.2.0"
  }
}

IntentTrace

requiredenumstring
reason_code
Reason for abandonment. This enum is extensible: servers SHOULD accept unrecognized values and treat them as "other" (see RFC Section 7.2). Validators SHOULD be configured for lenient enum handling.
Possible values
price_sensitivity
shipping_cost
shipping_speed
product_fit
trust_security
returns_policy
payment_options
comparison
timing_deferred
other
string
trace_summary
A generated summary of the specific objection or negotiation gap.
object
metadata

{
  "reason_code": "price_sensitivity",
  "trace_summary": "Customer mentioned the price was higher than expected and wanted to compare with other options",
  "metadata": {
    "compared_sites": 3
  }
}

CancelSessionRequest

IntentTrace
intent_trace

{
  "intent_trace": {
    "reason_code": "price_sensitivity",
    "trace_summary": "Customer mentioned the price was higher than expected"
  }
}

Error

Protocol-level error returned in 4xx/5xx responses when the server cannot return a valid CheckoutSession at all (e.g. malformed request or unexpected failure). Use Error—not MessageError—when there is no valid session state to return. type semantics: invalid_request — malformed request, missing required fields, or invalid JSON; request_not_idempotent — idempotency violation; processing_error — unexpected server-side failure; service_unavailable — temporary unavailability.

requiredenumstring
type
Error type indicating the category of protocol-level error
Possible values
invalid_request
request_not_idempotent
processing_error
service_unavailable
requiredstring
code
Implementation-defined error code
requiredstring
message
Human-readable error message
string
param
RFC 9535 JSONPath (optional)

{
  "type": "invalid_request",
  "code": "missing_required_field",
  "message": "The 'currency' field is required",
  "param": "$.currency"
}
Documentation | Agentic Commerce Protocol