> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asva-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ACP Tool Endpoints: Full Schema and Field Reference

> Complete request and response schemas for the three required ACP endpoints: checkout creation, session update, and purchase completion.

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

<ParamField body="items" type="array" required>
  Array of items to include in the checkout session.
</ParamField>

<ParamField body="items[].product_id" type="string" required>
  Unique identifier for the product.
</ParamField>

<ParamField body="items[].variant_id" type="string">
  Variant identifier — required when the product has size, color, or other options.
</ParamField>

<ParamField body="items[].quantity" type="integer" required>
  Number of units to purchase.
</ParamField>

<ParamField body="shipping_address" type="object">
  Destination address. Required if your catalog ships physical goods.
</ParamField>

<ParamField body="shipping_address.name" type="string">
  Full name of the recipient.
</ParamField>

<ParamField body="shipping_address.street" type="string">
  Street address line.
</ParamField>

<ParamField body="shipping_address.city" type="string">
  City.
</ParamField>

<ParamField body="shipping_address.state" type="string">
  State or province code (e.g. `"CA"`).
</ParamField>

<ParamField body="shipping_address.zip" type="string">
  Postal code.
</ParamField>

<ParamField body="shipping_address.country" type="string">
  ISO 3166-1 alpha-2 country code (e.g. `"US"`).
</ParamField>

<ParamField body="idempotency_key" type="string" required>
  Unique key for this request. Identical keys must return the same response without creating a duplicate session.
</ParamField>

**Example request:**

```json theme={null}
{
  "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

<ResponseField name="checkout_id" type="string">
  Unique identifier for the checkout session. Pass this to subsequent update and complete calls.
</ResponseField>

<ResponseField name="status" type="string">
  Current session state. Always `"pending_confirmation"` on creation.
</ResponseField>

<ResponseField name="items" type="array">
  Echoed item list with resolved names and prices.
</ResponseField>

<ResponseField name="items[].product_id" type="string">
  Product identifier.
</ResponseField>

<ResponseField name="items[].variant_id" type="string">
  Variant identifier.
</ResponseField>

<ResponseField name="items[].name" type="string">
  Human-readable product and variant label.
</ResponseField>

<ResponseField name="items[].quantity" type="integer">
  Quantity requested.
</ResponseField>

<ResponseField name="items[].unit_price" type="object">
  Price per unit with `amount` (integer, smallest currency unit) and `currency` (ISO 4217).
</ResponseField>

<ResponseField name="subtotal" type="object">
  Sum of item prices before shipping and tax, with `amount` and `currency`.
</ResponseField>

<ResponseField name="shipping_options" type="array">
  Available shipping methods. Each has `id`, `name`, and `cost`.
</ResponseField>

<ResponseField name="tax_estimate" type="object">
  Estimated tax with `amount` and `currency`. May be refined at completion.
</ResponseField>

<ResponseField name="expires_at" type="string">
  ISO 8601 timestamp when this session expires. Default is 15 minutes from creation.
</ResponseField>

**Example response:**

```json theme={null}
{
  "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

<ParamField body="shipping_option_id" type="string">
  The `id` of the shipping option selected by the user.
</ParamField>

**Example request:**

```json theme={null}
{
  "shipping_option_id": "express"
}
```

### Response fields

<ResponseField name="checkout_id" type="string">
  Identifier of the updated session.
</ResponseField>

<ResponseField name="status" type="string">
  Current session state. Remains `"pending_confirmation"` after a successful update.
</ResponseField>

<ResponseField name="selected_shipping" type="object">
  The confirmed shipping selection with `id`, `name`, and `cost`.
</ResponseField>

<ResponseField name="total" type="object">
  Updated total including subtotal, selected shipping, and tax, with `amount` and `currency`.
</ResponseField>

**Example response:**

```json theme={null}
{
  "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

<ParamField body="payment_method" type="object" required>
  Payment method details from your PSP.
</ParamField>

<ParamField body="payment_method.type" type="string" required>
  Payment method type. Use `"card"` for Stripe card tokens.
</ParamField>

<ParamField body="payment_method.token" type="string" required>
  Tokenized payment credential from your PSP. Use `"tok_visa_4242"` in staging.
</ParamField>

<ParamField body="shipping_option_id" type="string">
  Shipping option to apply if not already set in a prior update call.
</ParamField>

<ParamField body="idempotency_key" type="string" required>
  Unique key for this completion request. Must differ from the key used on create.
</ParamField>

**Example request:**

```json theme={null}
{
  "payment_method": {
    "type": "card",
    "token": "tok_visa_4242"
  },
  "shipping_option_id": "standard",
  "idempotency_key": "idem_confirm_abc123xyz"
}
```

### Response fields

<ResponseField name="order_id" type="string">
  Unique identifier for the confirmed order.
</ResponseField>

<ResponseField name="status" type="string">
  Order status. `"confirmed"` on success.
</ResponseField>

<ResponseField name="total" type="object">
  Final charged amount with `amount` and `currency`.
</ResponseField>

<ResponseField name="estimated_delivery" type="string">
  ISO 8601 date string for expected delivery.
</ResponseField>

<ResponseField name="confirmation_number" type="string">
  Human-readable order reference for customer support.
</ResponseField>

<ResponseField name="receipt_url" type="string">
  URL to the order receipt page.
</ResponseField>

**Example response:**

```json theme={null}
{
  "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         |

<Warning>
  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.
</Warning>

## 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

## Related

<CardGroup cols={2}>
  <Card title="ACP end-to-end implementation" icon="list-check" href="/acp/implementation">
    State machine and full validation checklist.
  </Card>

  <Card title="ACP instant checkout UX patterns" icon="bolt" href="/acp/instant-checkout">
    UX patterns and failure state handling.
  </Card>
</CardGroup>