Skip to main content

​
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.

​
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.
ParameterTypeDescription
itemsarrayArray of items you can purchase. (Required)
buyerhash (optional)Information about the buyer.
fulfillment_addresshash (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": "[email protected]",
    "phone_number": "+1234567890"
  },
  "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.
ParameterTypeDescription
idstringUnique identifier for the Checkout Session. (Required)
buyerhash (optional)Information about the buyer.
payment_providerhash (optional)Payment provider configuration and supported payment methods.
statusstringCurrent 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": "[email protected]",
    "phone_number": "+1234567890"
  },
  "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.
ParameterTypeDescription
idstringUnique identifier for the checkout process. (Required)
Example request: 
GET /checkouts/:id

​
Response

The response returns the current state of the checkout from the seller.
ParameterTypeDescription
idstringUnique identifier for the checkout session. (Required)
buyerhash (optional)Information about the buyer.
payment_providerhash (optional)Payment provider configuration and supported payment methods.
statusstringCurrent 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": "[email protected]",
    "phone_number": "+1234567890"
  },
  "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.
ParameterTypeDescription
idstringUnique identifier for the checkout process. (Required)
buyerhash (optional)Information about the buyer.
itemsarray (optional)Updated array of items to be purchased.
fulfillment_addresshash (optional)Updated fulfillment address.
fulfillment_option_idstring (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.
ParameterTypeDescription
idstringUnique identifier for the Checkout Session. (Required)
buyerhash (optional)Information about the buyer.
payment_providerhash (optional)Payment provider configuration and supported payment methods.
statusstringCurrent 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": "[email protected]",
    "phone_number": "+1234567890"
  },
  "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.
ParameterTypeDescription
idstringUnique identifier for the checkout process. (Required)
buyerhash (optional)Information about the buyer.
payment_datahashPayment 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.
ParameterTypeDescription
idstringUnique identifier for the Checkout Session. (Required)
buyerhash (optional)Information about the buyer.
payment_providerhash (optional)Payment provider configuration and supported payment methods.
statusstringCurrent 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": "[email protected]",
    "phone_number": "+1234567890"
  },
  "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.
ParameterTypeDescription
idstringUnique 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.
ParameterTypeDescription
idstringUnique identifier for the Checkout Session. (Required)
buyerhash (optional)Information about the buyer.
payment_providerhash (optional)Payment provider configuration and supported payment methods.
statusstringCurrent 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": "[email protected]",
    "phone_number": "+1234567890"
  },
  "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.
ParameterTypeDescription
first_namestringThe first name of the buyer. (Required)
last_namestringThe last name of the buyer. (Required)
emailstringThe email of the buyer. Required
phone_numberstring (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.
ParameterTypeDescription
idstringUnique identifier for the item. (Required)
quantityintegerThe requested quantity of the item for this checkout. (Required)

​
LineItem

The LineItem includes provides about the item added to the checkout, including the amount.
ParameterTypeDescription
idstringUnique identifier for the line item. (Required)
itemhashThe item details. (Required)
base_amountintegerThe base amount of the line item. (Required)
discountintegerThe discount amount of the line item. (Required)
totalintegerThe total amount of the line item. (Required)
subtotalintegerThe subtotal amount of the line item. (Required)
taxintegerThe tax amount of the line item. (Required)

​
Address

The Address provides the buyer’s shipping or billing address.
ParameterTypeDescription
namestringName of the person to whom the items are fulfilled. (Required)
line_onestringAddress line 1 (e.g., street, PO Box, or company name). (Required)
line_twostring (optional)Address line 2 (e.g., apartment, suite, unit, or building).
citystringCity, district, suburb, town, or village. (Required)
statestringState, county, province, or region. (Required)
countrystringTwo-letter country code (ISO 3166-1 alpha-2). (Required)
postal_codestringZIP or postal code. (Required)

​
PaymentData

The PaymentData provides the buyer’s payment details, including the tokenized value and the payment provider.
ParameterTypeDescription
tokenstringThe secure reference to a payment credential. (Required)
providerstringThe payment provider that the payment data is for. (Required)
billing_addresshash (optional)Billing address for the payment method.

​
Total

The Total provides a summary of the overall total.
ParameterTypeDescription
typeenumThe 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.
ParameterTypeDescription
typeenumThe 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.
ParameterTypeDescription
typeenumThe 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.
ParameterTypeDescription
providerstringThe 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.
ParameterTypeDescription
typeenumString 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.
ParameterTypeDescription
typeenumString 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.
ParameterTypeDescription
typeenumThe 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. | The Link defines the parameters for links related to policies and agreements.
ParameterTypeDescription
typeenumString 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.
ParameterTypeDescription
idstringUnique identifier for the order. (Required)
checkout_session_idstringReference to the Checkout Session that the order originated from. (Required)
permalink_urlstringThe permalink URL for the order. (Required)

​
Event

The Event defines the parameters for events related to order creation and updates.
ParameterTypeDescription
typeenumThe 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.
ParameterTypeDescription
typestringThe string value represents the type of event data. For order data, use the value order. (Required)
checkout_session_idstringID that identifies the Checkout Session that created this order. (Required)
permalink_urlstringThe URL points to the order. Customers can visit this URL and provide their email address to view order details. (Required)
statusenumString 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.
ParameterTypeDescription
typeenumThe type of refund. (Required)
Possible values: store_credit | original_payment | | amount | integer | The amount of the refund. (Required) |