Build the Agentic Commerce Protocol checkout endpointsPrivate preview

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.

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": "john.doe@example.com",
    "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.

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": "john.doe@example.com",
    "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.

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": "john.doe@example.com",
    "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.

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": "john.doe@example.com",
    "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.

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": "john.doe@example.com",
    "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.

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": "john.doe@example.com",
    "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.

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

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

type

enum

The type of total. Required

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

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`

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

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

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

Parameter	Type	Description
type	`enum`	The type of event. Required Possible values: `order_created` \| `order_updated`
data	`hash`	Event data containing order information. Required

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

Parameter	Type	Description
type	`enum`	The type of refund. Required Possible values: `store_credit` \| `original_payment`
amount	`integer`	The amount of the refund. Required

type

enum

The type of refund. Required

Possible values: store_credit | original_payment

amount integer The amount of the refund. Required