Agentic Commerce Protocol Checkout Guide

Learn how to use the Agentic Commerce Protocol to create, update, and complete checkout flows.

Build the Agentic Commerce Protocol checkout endpoints

Learn about the Agentic Commerce Protocol specification.

You can use the Agentic Commerce Protocol (ACP) to enable AI agents to manage commerce transactions between buyers and sellers. This specification defines the methods and data structures for creating, updating, and completing checkout flows.

You can find examples for REST integrations below.

Where ACP fits

ACP is the transaction layer of StateSet’s agentic commerce offering. For the full conversation‑to‑fulfillment architecture, see Stateset iCommerce Architecture.

Create a Checkout Session

You can create a new Checkout Session with buyer details, line items, and shipping information.

Request

Specify the parameters required for your request.

Parameter	Type	Description
items	array	Array of items you can purchase. (Required)
buyer	hash (optional)	Information about the buyer.
fulfillment_address	hash (optional)	Address where the order will ship.

Example request:

POST /checkouts
{
  "items": [
    {
      "id": "item_123",
      "quantity": 2
    }
  ],
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]"
  },
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "123 Main St",
    "line_two": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105"
  }
}

Response

The response returns the current state of the checkout from the seller.

Parameter	Type	Description
id	string	Unique identifier for the Checkout Session. (Required)
buyer	hash (optional)	Information about the buyer.
payment_provider	hash (optional)	Payment provider configuration and supported payment methods.
status	string	Current status of the checkout process. (Required)

Possible values: not_ready_for_payment | ready_for_payment | completed | canceled | in_progress | | currency | string | Three-letter ISO currency code, in lowercase. (Required) | | line_items | array | Array of line items in the checkout process. (Required) | | fulfillment_address | hash (optional) | Address where the order will ship. | | fulfillment_options | array | Available shipping and fulfillment options. (Required) | | fulfillment_option_id | string (optional) | ID of the currently selected fulfillment option. | | totals | array | Overview of charges and discounts. (Required) | | messages | array | Array of messages or notifications related to the checkout process. (Required) | | links | array | Array of links related to the checkout process. (Required) |

Example response:

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]"
  },
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 2
      },
      "base_amount": 2000,
      "discount": 0,
      "total": 2000,
      "subtotal": 2000,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "123 Main St",
    "line_two": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 2000
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 2250
    }
  ],
  "messages": [],
  "links": []
}

Retrieve a Checkout object

To retrieve an existing Checkout Session using its ID, make a request to the appropriate API endpoint with the ID included in the request.

Request

Specify the parameters required for your request.

Parameter	Type	Description
id	string	Unique identifier for the checkout process. (Required)

Example request:

GET /checkouts/:id

Response

The response returns the current state of the checkout from the seller.

Parameter	Type	Description
id	string	Unique identifier for the checkout session. (Required)
buyer	hash (optional)	Information about the buyer.
payment_provider	hash (optional)	Payment provider configuration and supported payment methods.
status	string	Current status of the checkout process. (Required)

Possible values: not_ready_for_payment | ready_for_payment | completed | canceled | in_progress | | currency | string | Three-letter ISO currency code, in lowercase. (Required) | | line_items | array | Array of line items in the checkout process. (Required) | | fulfillment_address | hash (optional) | Address where the order will ship. | | fulfillment_options | array | Available shipping and fulfillment options. (Required) | | fulfillment_option_id | string (optional) | ID of the currently selected fulfillment option. | | totals | array | Overview of charges and discounts. (Required) | | messages | array | Array of messages or notifications related to the checkout process. (Required) | | links | array | Array of links related to the checkout process. (Required) |

Example response:

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]"
  },
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 2
      },
      "base_amount": 2000,
      "discount": 0,
      "total": 2000,
      "subtotal": 2000,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "123 Main St",
    "line_two": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 2000
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 2250
    }
  ],
  "messages": [],
  "links": []
}

Update a Checkout Session

You can update an existing Checkout Session by modifying line items, shipping address, or fulfillment options.

Request

Specify the parameters required for your request.

Parameter	Type	Description
id	string	Unique identifier for the checkout process. (Required)
buyer	hash (optional)	Information about the buyer.
items	array (optional)	Updated array of items to be purchased.
fulfillment_address	hash (optional)	Updated fulfillment address.
fulfillment_option_id	string (optional)	Identifier for the selected fulfillment option.

Example request:

PUT /checkouts/:id
{
  "items": [
    {
      "id": "item_123",
      "quantity": 3
    },
    {
      "id": "item_456",
      "quantity": 1
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_option_id": "shipping_fast"
}

Response

The response returns the current state of the checkout from the seller.

Parameter	Type	Description
id	string	Unique identifier for the Checkout Session. (Required)
buyer	hash (optional)	Information about the buyer.
payment_provider	hash (optional)	Payment provider configuration and supported payment methods.
status	string	Current status of the checkout process. (Required)

Possible values: not_ready_for_payment | ready_for_payment | completed | canceled | in_progress | | currency | string | Three-letter ISO currency code, in lowercase. (Required) | | line_items | array | Array of line items in the checkout process. (Required) | | fulfillment_address | hash (optional) | Address where the order will ship. | | fulfillment_options | array | Available shipping and fulfillment options. (Required) | | fulfillment_option_id | string (optional) | ID of the currently selected fulfillment option. | | totals | array | Overview of charges and discounts. (Required) | | messages | array | Array of messages or notifications related to the checkout process. (Required) | | links | array | Array of links related to the checkout process. (Required) |

Example response:

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]"
  },
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [],
  "links": []
}

Complete a Checkout

You can complete the checkout process by processing the payment and creating an order.

Request

Specify the parameters required for your request.

Parameter	Type	Description
id	string	Unique identifier for the checkout process. (Required)
buyer	hash (optional)	Information about the buyer.
payment_data	hash	Payment method details for processing the transaction. (Required)

Example request:

POST /checkouts/:id/complete
{
  "payment_data": {
    "token": "spt_123",
    "provider": "stripe",
    "billing_address": {
      "name": "John Doe",
      "line_one": "123 Main St",
      "line_two": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94105"
    }
  }
}

Response

The response returns the current state of the checkout from the seller.

Parameter	Type	Description
id	string	Unique identifier for the Checkout Session. (Required)
buyer	hash (optional)	Information about the buyer.
payment_provider	hash (optional)	Payment provider configuration and supported payment methods.
status	string	Current status of the checkout process. (Required)

Possible values: not_ready_for_payment | ready_for_payment | completed | canceled | in_progress | | currency | string | Three-letter ISO currency code, in lowercase. (Required) | | line_items | array | Array of line items in the checkout process. (Required) | | fulfillment_address | hash (optional) | Address where the order will ship. | | fulfillment_options | array | Available shipping and fulfillment options. (Required) | | fulfillment_option_id | string (optional) | ID of the currently selected fulfillment option. | | totals | array | Overview of charges and discounts. (Required) | | messages | array | Array of messages or notifications related to the checkout process. (Required) | | links | array | Array of links related to the checkout process. (Required) |

Example response:

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]"
  },
  "status": "completed",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [],
  "links": []
}

Cancel a Checkout

You can cancel an existing Checkout Session if necessary.

Request

Specify the parameters required for your request.

Parameter	Type	Description
id	string	Unique identifier for the checkout process. (Required)

Example request:

POST /checkouts/:id/cancel
{}

Response

The response returns the current state of the checkout from the seller.

Parameter	Type	Description
id	string	Unique identifier for the Checkout Session. (Required)
buyer	hash (optional)	Information about the buyer.
payment_provider	hash (optional)	Payment provider configuration and supported payment methods.
status	string	Current status of the checkout process. (Required)

Possible values: not_ready_for_payment | ready_for_payment | completed | canceled | in_progress | | currency | string | Three-letter ISO currency code, in lowercase. (Required) | | line_items | array | Array of line items in the checkout process. (Required) | | fulfillment_address | hash (optional) | Address where the order will ship. | | fulfillment_options | array | Available shipping and fulfillment options. (Required) | | fulfillment_option_id | string (optional) | ID of the currently selected fulfillment option. | | totals | array | Overview of charges and discounts. (Required) | | messages | array | Array of messages or notifications related to the checkout process. (Required) | | links | array | Array of links related to the checkout process. (Required) |

Example response:

{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone_number": "[phone]"
  },
  "status": "canceled",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [
    {
      "type": "info",
      "content_type": "plain",
      "content": "Checkout cancelled: Customer changed their mind"
    }
  ],
  "links": []
}

Data structures

This section outlines the data structures involved in the checkout process.

Buyer

The buyer is an individual who initiates the purchase.

Parameter	Type	Description
first_name	string	The first name of the buyer. (Required)
last_name	string	The last name of the buyer. (Required)
email	string	The email of the buyer. Required
phone_number	string (optional)	The phone number of the buyer.

Item

The Item is a product or service that the buyer requests to purchase, along with its quantity.

Parameter	Type	Description
id	string	Unique identifier for the item. (Required)
quantity	integer	The requested quantity of the item for this checkout. (Required)

LineItem

The LineItem includes provides about the item added to the checkout, including the amount.

Parameter	Type	Description
id	string	Unique identifier for the line item. (Required)
item	hash	The item details. (Required)
base_amount	integer	The base amount of the line item. (Required)
discount	integer	The discount amount of the line item. (Required)
total	integer	The total amount of the line item. (Required)
subtotal	integer	The subtotal amount of the line item. (Required)
tax	integer	The tax amount of the line item. (Required)

Address

The Address provides the buyer’s shipping or billing address.

Parameter	Type	Description
name	string	Name of the person to whom the items are fulfilled. (Required)
line_one	string	Address line 1 (e.g., street, PO Box, or company name). (Required)
line_two	string (optional)	Address line 2 (e.g., apartment, suite, unit, or building).
city	string	City, district, suburb, town, or village. (Required)
state	string	State, county, province, or region. (Required)
country	string	Two-letter country code (ISO 3166-1 alpha-2). (Required)
postal_code	string	ZIP or postal code. (Required)

PaymentData

The PaymentData provides the buyer’s payment details, including the tokenized value and the payment provider.

Parameter	Type	Description
token	string	The secure reference to a payment credential. (Required)
provider	string	The payment provider that the payment data is for. (Required)
billing_address	hash (optional)	Billing address for the payment method.

Total

The Total provides a summary of the overall total.

Parameter	Type	Description
type	enum	The type of total. (Required)

Possible values: items_base_amount | items_discount | subtotal | discount | fulfillment | tax | fee | total | | display_text | string | The display text for the total. (Required) | | amount | integer | The amount of the total. (Required) |

FulfillmentOption

Fulfillment options are either shipping or digital. See ShippingFulfillmentOption and DigitalFulfillmentOption for specific implementations.

ShippingFulfillmentOption

The ShippingFulfillmentOption defines the parameters for shipping fulfillment options, including the carrier information and delivery times.

Parameter	Type	Description
type	enum	The type of fulfillment option. (Required)

Possible values: shipping | | id | string | Unique identifier for the shipping fulfillment option. (Required) | | title | string | The title of the shipping fulfillment option. (Required) | | subtitle | string (optional) | The subtitle of the shipping fulfillment option. | | carrier | string (optional) | The carrier of the shipping fulfillment option. | | earliest_delivery_time | string (optional) | The earliest delivery time of the shipping fulfillment option (ISO 8601 format). | | latest_delivery_time | string (optional) | The latest delivery time of the shipping fulfillment option (ISO 8601 format). | | subtotal | integer | The subtotal of the shipping fulfillment option. (Required) | | tax | integer | The tax of the shipping fulfillment option. (Required) | | total | integer | The total of the shipping fulfillment option. (Required) |

DigitalFulfillmentOption

The DigitalFulfillmentOption defines the parameters for digital fulfillment options, including the title and pricing information.

Parameter	Type	Description
type	enum	The type of fulfillment option. (Required)

Possible values: digital | | id | string | Unique identifier for the digital fulfillment option. (Required) | | title | string | The title of the digital fulfillment option. (Required) | | subtitle | string (optional) | The subtitle of the digital fulfillment option. | | subtotal | integer | The subtotal of the digital fulfillment option. (Required) | | tax | integer | The tax of the digital fulfillment option. (Required) | | total | integer | The total of the digital fulfillment option. (Required) |

PaymentProvider

The PaymentProvider defines the seller’s supported payment provider and available methods.

Parameter	Type	Description
provider	string	The seller’s payment provider. (Required)

Possible values: stripe | | supported_payment_methods | array | The payment methods allowed by the seller. (Required)

Possible values: card |

Message

Messages are either informational or error messages.

InfoMessage

The InfoMessage represents informational messages, detailing the type and content.

Parameter	Type	Description
type	enum	String value representing message type.

Possible values: info | | param | string (optional) | RFC 9535 JSONPath to the component of the Checkout Session that the message references. | | content_type | enum (optional) | The type of content of the message.

Possible values: plain | markdown | | content | string | The content of the message. |

ErrorMessage

The ErrorMessage represents error messages, detailing the type and code.

Parameter	Type	Description
type	enum	String value representing message type.

Possible values: error | | code | enum | The code of the error.

Possible values: missing | invalid | out_of_stock | payment_declined | requires_sign_in | requires_3ds | | param | string (optional) | RFC 9535 JSONPath to the component of the Checkout Session that the message references. | | content_type | enum (optional) | The type of content of the message.

Possible values: plain | markdown | | content | string | The content of the message. |

Error

The Error defines the parameters related to errors occurring during the checkout process.

Parameter	Type	Description
type	enum	The type of error. (Required)

Possible values: invalid_request | request_not_idempotent | processing_error | service_unavailable | | code | string | The implementation-defined error code. (Required) | | message | string | The message of the error. (Required) | | param | string (optional) | RFC 9535 JSONPath to the component of the Checkout Session that the message references. |

Link

The Link defines the parameters for links related to policies and agreements.

Parameter	Type	Description
type	enum	String value representing the type of link. (Required)

Possible values: terms_of_use | privacy_policy | seller_shop_policies | | url | string | The URL of the link. (Required) |

Order

The Order provides the result of the checkout process and offers details to the buyer for order lookup.

Parameter	Type	Description
id	string	Unique identifier for the order. (Required)
checkout_session_id	string	Reference to the Checkout Session that the order originated from. (Required)
permalink_url	string	The permalink URL for the order. (Required)

Event

The Event defines the parameters for events related to order creation and updates.

Parameter	Type	Description
type	enum	The type of event. (Required)

Possible values: order_created | order_updated | | data | hash | Event data containing order information. (Required) |

OrderEventData

The OrderEventData includes data related to order events.

Parameter	Type	Description
type	string	The string value represents the type of event data. For order data, use the value order. (Required)
checkout_session_id	string	ID that identifies the Checkout Session that created this order. (Required)
permalink_url	string	The URL points to the order. Customers can visit this URL and provide their email address to view order details. (Required)
status	enum	String representing the latest status of the order. (Required)

Possible values: created | manual_review | confirmed | canceled | shipped | fulfilled | | refunds | array | List of refunds that have been issued for the order. (Required) |

Refund

The Refund defines the parameters for managing refunds associated with completed orders.

Parameter	Type	Description
type	enum	The type of refund. (Required)

Possible values: store_credit | original_payment | | amount | integer | The amount of the refund. (Required) |