ACP Tool Endpoints: Full Schema and Field Reference

ACP requires three primary endpoints that map directly to stages in the checkout state machine. Every field, error code, and latency requirement in this reference is enforced by ACP-compatible agents — return unexpected shapes and the agent will not be able to relay accurate information to the user.

Endpoint overview

Endpoint	Method	Purpose
`/acp/checkout/create`	POST	Create a new checkout session
`/acp/checkout/:id/update`	PATCH	Update cart or session details
`/acp/checkout/:id/complete`	POST	Confirm and complete the purchase

The following endpoints are optional but recommended:

Endpoint	Method	Purpose
`/acp/products/search`	GET	Search catalog — backs the `search_products` tool
`/acp/orders/:id`	GET	Order status and tracking
`/acp/orders/history`	GET	User’s order history for reorder flows

`POST /acp/checkout/create`

Creates a new checkout session with the selected items. Call this endpoint when the initiate_checkout tool is invoked.

Request parameters

array

required

Array of items to include in the checkout session.

string

required

Unique identifier for the product.

string

Variant identifier — required when the product has size, color, or other options.

integer

required

Number of units to purchase.

object

Destination address. Required if your catalog ships physical goods.

string

Full name of the recipient.

string

Street address line.

string

City.

string

State or province code (e.g. "CA").

string

Postal code.

string

ISO 3166-1 alpha-2 country code (e.g. "US").

string

required

Unique key for this request. Identical keys must return the same response without creating a duplicate session.

Example request:

{
  "items": [
    {
      "product_id": "prod_123",
      "variant_id": "var_123_10_black",
      "quantity": 1
    }
  ],
  "shipping_address": {
    "name": "Jane Smith",
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "country": "US"
  },
  "idempotency_key": "idem_abc123xyz"
}

Response fields

string

Unique identifier for the checkout session. Pass this to subsequent update and complete calls.

string

Current session state. Always "pending_confirmation" on creation.

array

Echoed item list with resolved names and prices.

string

Product identifier.

string

Variant identifier.

string

Human-readable product and variant label.

integer

Quantity requested.

object

Price per unit with amount (integer, smallest currency unit) and currency (ISO 4217).

object

Sum of item prices before shipping and tax, with amount and currency.

array

Available shipping methods. Each has id, name, and cost.

object

Estimated tax with amount and currency. May be refined at completion.

string

ISO 8601 timestamp when this session expires. Default is 15 minutes from creation.

Example response:

{
  "checkout_id": "chk_abc123",
  "status": "pending_confirmation",
  "items": [
    {
      "product_id": "prod_123",
      "variant_id": "var_123_10_black",
      "name": "Running Shoes — Size 10 Black",
      "quantity": 1,
      "unit_price": { "amount": 12999, "currency": "USD" }
    }
  ],
  "subtotal": { "amount": 12999, "currency": "USD" },
  "shipping_options": [
    {
      "id": "standard",
      "name": "Standard Shipping (5-7 days)",
      "cost": { "amount": 599, "currency": "USD" }
    },
    {
      "id": "express",
      "name": "Express (2 days)",
      "cost": { "amount": 1499, "currency": "USD" }
    }
  ],
  "tax_estimate": { "amount": 1170, "currency": "USD" },
  "expires_at": "2026-04-10T13:15:00Z"
}

Error responses:

Status	Code	Description
409	`out_of_stock`	One or more items are unavailable
422	`invalid_address`	Shipping address failed validation
429	`rate_limited`	Too many checkout attempts from this user

`PATCH /acp/checkout/:id/update`

Updates mutable fields on an existing session — most commonly the selected shipping option. Call this after the user chooses a shipping method.

Request parameters

string

The id of the shipping option selected by the user.

Example request:

{
  "shipping_option_id": "express"
}

Response fields

string

Identifier of the updated session.

string

Current session state. Remains "pending_confirmation" after a successful update.

object

The confirmed shipping selection with id, name, and cost.

object

Updated total including subtotal, selected shipping, and tax, with amount and currency.

Example response:

{
  "checkout_id": "chk_abc123",
  "status": "pending_confirmation",
  "selected_shipping": {
    "id": "express",
    "name": "Express (2 days)",
    "cost": { "amount": 1499, "currency": "USD" }
  },
  "total": { "amount": 15668, "currency": "USD" }
}

`POST /acp/checkout/:id/complete`

Processes payment and confirms the order. Call this endpoint when confirm_purchase is invoked — only after the user has explicitly confirmed the purchase summary.

Request parameters

object

required

Payment method details from your PSP.

string

required

Payment method type. Use "card" for Stripe card tokens.

string

required

Tokenized payment credential from your PSP. Use "tok_visa_4242" in staging.

string

Shipping option to apply if not already set in a prior update call.

string

required

Unique key for this completion request. Must differ from the key used on create.

Example request:

{
  "payment_method": {
    "type": "card",
    "token": "tok_visa_4242"
  },
  "shipping_option_id": "standard",
  "idempotency_key": "idem_confirm_abc123xyz"
}

Response fields

string

Unique identifier for the confirmed order.

string

Order status. "confirmed" on success.

object

Final charged amount with amount and currency.

string

ISO 8601 date string for expected delivery.

string

Human-readable order reference for customer support.

string

URL to the order receipt page.

Example response:

{
  "order_id": "order_xyz789",
  "status": "confirmed",
  "total": { "amount": 14768, "currency": "USD" },
  "estimated_delivery": "2026-04-17",
  "confirmation_number": "ORD-2026-XYZ789",
  "receipt_url": "https://yourstore.com/orders/order_xyz789"
}

Error responses:

Status	Code	Description
402	`payment_declined`	Payment failed
409	`out_of_stock`	Item became unavailable before confirmation
410	`session_expired`	Checkout session is past `expires_at`
422	`validation_error`	Missing or invalid required fields

Latency requirements

Endpoint	Max response time
Create checkout	3 seconds
Update checkout	1 second
Complete checkout	5 seconds

If your complete endpoint exceeds 5 seconds, some ACP-compatible agents will time out and retry — potentially without an idempotency key. Always implement idempotency on complete to prevent duplicate orders.

Response validation checklist

Run through this list before going live:

All responses include Content-Type: application/json
All amounts are in the smallest currency unit (cents for USD)
Error responses include both code and a human-readable message
expires_at is returned on checkout creation
Order confirmation includes order_id and estimated_delivery
Response times are within the limits above
Idempotency keys prevent duplicate orders on retry

ACP end-to-end implementation

State machine and full validation checklist.

ACP instant checkout UX patterns

UX patterns and failure state handling.

Get Started

UCP

ACP

Attribution

Guides

ACP Tool Endpoints: Full Schema and Field Reference

Endpoint overview

`POST /acp/checkout/create`

Request parameters

Response fields

`PATCH /acp/checkout/:id/update`

Request parameters

Response fields

`POST /acp/checkout/:id/complete`

Request parameters

Response fields

Latency requirements

Response validation checklist

ACP end-to-end implementation

ACP instant checkout UX patterns

​Endpoint overview

​POST /acp/checkout/create

​Request parameters

​Response fields

​PATCH /acp/checkout/:id/update

​Request parameters

​Response fields

​POST /acp/checkout/:id/complete

​Request parameters

​Response fields

​Latency requirements

​Response validation checklist

​Related

ACP end-to-end implementation

ACP instant checkout UX patterns

Endpoint overview

`POST /acp/checkout/create`

Request parameters

Response fields

`PATCH /acp/checkout/:id/update`

Request parameters

Response fields

`POST /acp/checkout/:id/complete`

Request parameters

Response fields

Latency requirements

Response validation checklist

Related