--- title: "AI agent integration with Agentic Commerce Suite" description: "Integrate with the Adyen Agentic Commerce Suite API to enable your AI agent platform to execute transactions with Adyen merchants." url: "https://docs.adyen.com/online-payments/agentic-commerce/ai-agent-integration" source_url: "https://docs.adyen.com/online-payments/agentic-commerce/ai-agent-integration.md" canonical: "https://docs.adyen.com/online-payments/agentic-commerce/ai-agent-integration" last_modified: "2026-05-08T17:09:17+02:00" language: "en" --- # AI agent integration with Agentic Commerce Suite Integrate with the Adyen Agentic Commerce Suite API to enable your AI agent platform to execute transactions with Adyen merchants. The Adyen Agentic Commerce Suite API acts as a bridge between your AI agent platform and our merchants. This enables your agents to execute transactions on behalf of shoppers who use your AI agents. You communicate with Adyen through our API endpoints, and you do not communicate directly with merchants. Adyen handles the communication with our merchants and the downstream complexity of orchestrating stock validation, tax calculation, shipping, and payment authorization. We make the relevant information visible to your agents. ## Requirements | Requirement | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | This guide is for an integration using the OpenAI [Agentic Commerce Protocol (ACP)](https://developers.openai.com/commerce/guides/get-started). | | **User role** | Make sure that your Adyen credential has the following user role:- **Commerce Suite API**. | | **Setup steps** | Before you begin, make sure that you have:- Set up a Token Vault integration using the [Delegated Payment Spec with Adyen](/online-payments/agentic-commerce/delegated-payment-spec). | ## How it works Use the following base URL for the endpoints in the agentic commerce checkout lifecycle. The path parameter `{companyAccount}` is the Adyen account of the merchant the shopper makes the transaction with. | Environment | Base URL | | ----------- | ------------------------------------------------------------------------------ | | Test | `https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{companyAccount}` | | Live | `https://commerce-suite.adyen.com/commerce-suite/acp/v1/{companyAccount}` | The agentic commerce checkout lifecycle consists of up to five phases. | # | Phase | Method | Endpoint | Requirement | | - | -------------------- | ------ | ----------------------------------------- | ----------- | | 1 | **Create Session** | `POST` | `/checkout_sessions` | Mandatory | | 2 | **Get Session** | `GET` | `/checkout_sessions/{sessionId}` | Optional | | 3 | **Update Session** | `POST` | `/checkout_sessions/{sessionId}` | Mandatory | | 4 | **Complete Session** | `POST` | `/checkout_sessions/{sessionId}/complete` | Mandatory | | 5 | **Cancel Session** | `POST` | `/checkout_sessions/{sessionId}/cancel` | Optional | See [Sequence diagrams](#sequence-diagrams) for visual representations of the flows. ### Authentication The Adyen Agentic Commerce Suite uses **Bearer token authentication**. Pass your Adyen API key as the Bearer token in the `Authorization` header. Your API key must have the **Commerce Suite API** role. **Bearer token authentication** ```http Authorization: Bearer ADYEN_API_KEY Content-Type: application/json ``` Never expose your API key in a URL query string, or in agent-readable context. All calls must originate from your secure agent backend or token vault infrastructure. ## 1. Create Session Initializes a new checkout session with a list of items and optional buyer and fulfillment information. Adyen calls the merchant's backend to validate stock and compute real-time totals, then returns the authoritative session state to your agent. Method and endpoint: POST `/checkout_sessions` Creates a new checkout session. Returns HTTP 200 with line items, fulfillment options, totals, and a `payment_provider` block identifying the merchant's PSP and accepted payment methods. ### Request body | Parameter | Type | Required | Description | | ----------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `currency` | string (ISO 4217) · exactly 3 chars | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 3-letter settlement currency code, for example, `USD`, `EUR`, `GBP`. | | `items` | AcpItem\[] | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Items to add to the session. Each item requires an `id` and `quantity` ≥ 1. | | `buyer` | AcpBuyer | | Buyer contact details: `email`, `first_name`, `last_name`, `phone_number`. | | `fulfillment_address` | AcpAddress | | Shipping address. Required for physical goods where tax or shipping varies by location. | | `fulfillment_option_id` | string | | Pre-select a fulfillment option if already known. | | `affiliate_attribution` | AcpAffiliateAttribution | | Affiliate attribution data for tracking referral sources. Includes `provider`, `token`, `publisher_id`, `campaign_id`, and `touchpoint`. See [AcpAffiliateAttribution](#acpaffiliateattribution). | **Example request to create a checkout session** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/AdyenMerchantCompanyAccount/checkout_sessions \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "currency": "USD", "items": [{ "id": "01", "quantity": 1 }], "buyer": { "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace" }, "fulfillment_address": { "line_one": "123 Market St", "line_two": "", "city": "San Francisco", "state": "CA", "country": "US", "postal_code": "94103" } }' ``` ### Response Identical to `AcpCheckoutSessionResponse` plus a required `payment_provider` object. **Example response body for HTTP 200 OK** ```json { "id": "cs_8xzQk2TmNpR", "status": "ready_for_payment", "currency": "USD", "payment_provider": { "provider": "adyen", "merchant_id": "ADYEN_MERCHANT_ACCOUNT", "supported_payment_methods": ["scheme", "googlepay", "applepay"] }, "line_items": [{ "id": "li_001", "item": { "id": "prod_headphones_pro", "quantity": 1 }, "base_amount": 34900, "subtotal": 34900, "tax": 2967, "total": 37867 }], "fulfillment_options": [{ "id": "ship_standard", "type": "shipping", "carrier": "UPS", "title": "Standard Shipping", "subtitle": "5-7 business days", "subtotal": 799, "tax": 0, "total": 799 }], "totals": [], "messages": [], "links": [] } ``` ### Status codes | HTTP | Meaning | Description | | ---- | ------------- | ------------------------------------------------------------------------------------ | | 200 | OK | Session created. Use the returned `id` for all subsequent calls. | | 422 | Unprocessable | Business logic prevented creation (for example, out of stock). Inspect `messages[]`. | ## 2. (Optional) Get Session Retrieves the current authoritative state of a session. Use this to re-sync totals after an async event or verify status before confirming payment with the shopper. Method and endpoint: GET `/checkout_sessions/{sessionId}` No request body. Returns the full `AcpCheckoutSessionResponse` for the given session ID. ### Path parameters | Parameter | Type | Required | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | `companyAccount` | string | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your Adyen company account identifier. | | `sessionId` | string | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `id` returned from the Create Session call. | ### Status codes | HTTP | Meaning | Description | | ---- | --------- | ----------------------------------------- | | 200 | OK | Session found and returned. | | 404 | Not Found | Session ID does not exist or has expired. | ## 3. Update Session Updates an existing session with new items, address, buyer details, or a fulfillment selection. Each update re-triggers Adyen's call to the merchant's live calculator, ensuring your agent always has accurate totals. Method and endpoint: POST `/checkout_sessions/{sessionId}` Returns the full updated `AcpCheckoutSessionResponse`. Only fields present in the request body are applied. ### Request body This endpoint uses a dedicated `AcpUpdateCheckoutSessionRequest` schema. Unlike Create Session, no fields are required — include only what needs to change. | Parameter | Type | Required | Description | | --------------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------- | | **`currency`** | string (ISO 4217) | | Must match the currency set at session creation if provided. | | **`items`** | AcpItem\[] | | Replaces the entire item list. | | **`buyer`** | AcpBuyer | | Updated buyer contact information. | | **`fulfillment_address`** | AcpAddress | | Updated shipping address. Triggers recalculation of tax and shipping costs. | | **`fulfillment_option_id`** | string | | ID of the fulfillment option the shopper selected from `fulfillment_options[]` in the session response. | **Example request to update checkout session** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/AdyenMerchantCompanyAccount/checkout_sessions/cs_8xzQk2TmNpR \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "fulfillment_option_id": "ship_express", "fulfillment_address": { "line_one": "1 Infinite Loop", "line_two": "", "city": "Cupertino", "state": "CA", "country": "US", "postal_code": "95014" } }' ``` Call Update Session whenever the shopper changes their delivery address, selects a shipping tier, or modifies cart quantity. The response `line_items[].total`, `fulfillment_options[].total`, and `totals[]` are always authoritative — present these to the shopper before proceeding to Complete. ### Status codes | HTTP | Meaning | Description | | ---- | ------------- | --------------------------------------------------------------------------------------------- | | 200 | OK | Session updated. Response contains the latest authoritative state. | | 422 | Unprocessable | Update rejected by merchant logic (for example, item now out of stock). Inspect `messages[]`. | ## 4. Complete Session Finalizes the session by submitting the payment token from your agent's Token Vault. Adyen validates the token, optionally calls the merchant's commit endpoint for a pre-authorization risk check, executes payment authorization, and returns the result — including the created `order` object on success. Method and endpoint: POST `/checkout_sessions/{sessionId}/complete` Submits payment data and triggers authorization. Returns `AcpCompleteSessionResponse` — the full session state plus an `order` object on successful authorization. ### Request body | Parameter | Type | Required | Description | | ------------------ | -------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`payment_data`** | AcpPaymentData | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Payment token and provider. Must include `provider` (for example, `adyen`) and `token` — the PSP transaction token from your vault's `delegate_payment` call. | ### Example request **Complete checkout session request** ```bash curl https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/AdyenMerchantCompanyAccount/checkout_sessions/cs_8xzQk2TmNpR/complete \ -H 'Authorization: Bearer ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "payment_data": { "provider": "adyen", "token": "psp_tok_Ab7xQfN2YwR..." } }' ``` ### Success response **Example complete response body for HTTP 200 OK** ```json { "id": "cs_8xzQk2TmNpR", "status": "completed", "order": { "id": "ORD-2026-001", "checkout_session_id": "cs_8xzQk2TmNpR", "permalink_url": "https://merchant.com/orders/ORD-2026-001" }, "line_items": [], "fulfillment_options": [], "totals": [], "messages": [], "links": [] } ``` Present `order.permalink_url` to the shopper as their confirmation link. `order.id` is the unique order identifier — use it for post-purchase communication and support queries. ### Status codes | HTTP | Meaning | Description | | ---- | ------- | ------------------------------------------------------------------------------------------------------------ | | 200 | OK | Authorization executed. `order` present on success; `messages[]` contains details on declined authorization. | ## 5. (Optional) Cancel Session Cancels an active session that has not been completed. Call this when the shopper abandons checkout or your agent cannot proceed. Signals the merchant to release any reserved inventory. Method and endpoint: POST `/checkout_sessions/{sessionId}/cancel` No request body required. Returns `AcpCheckoutSessionResponse` with `status: "canceled"`. ### Status codes | HTTP | Meaning | Description | | ---- | ------- | -------------------------------------------------------------------------------------- | | 200 | OK | Session canceled. Response contains the final session state with `status: "canceled"`. | ## Testing Use the sandbox environment to test end-to-end before going live. The sandbox uses the same API spec and schemas as production. Use the following base URL for all sandbox requests besides Delegate Payment: ```text https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{companyAccount} ``` ### Sandbox endpoints | Operation | Method | Path | | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------- | | Create Session | `POST` | `/checkout_sessions` | | Get Session | `GET` | `/checkout_sessions/{sessionId}` | | Update Session | `POST` | `/checkout_sessions/{sessionId}` | | Complete Session | `POST` | `/checkout_sessions/{sessionId}/complete` | | Cancel Session | `POST` | `/checkout_sessions/{sessionId}/cancel` | | Delegate Payment | `POST` | `https://pal-test.adyen.com/paltokenization/servlet/Recurring/Agentic/acp/v1/agentic_commerce/delegate_payment` | The `delegate_payment` endpoint is part of our tokenization domain, not the Commerce Suite domain. It handles raw PSP credential material on behalf of the agent's Token Vault. Authenticate with `Authorization: Bearer` exactly as you would for all other Commerce Suite calls. ### Recommended test sequence To verify your integration, follow these steps: 1. Create a session. Make a POST `/checkout_sessions` request with your test API key in the `Authorization: Bearer` header. Note the returned `id` (for example, `cs_test_abc123`). 2. Update with address and fulfillment selection. Make a POST `/checkout_sessions/cs_test_abc123` request. Confirm that `status` is `ready_for_payment` and that the totals are finalized. 3. Delegate payment through the Token Vault. Make a POST `/delegate_payment` request with your test API key in the `Authorization: Bearer` header. Capture the returned `psp_transaction_token`. 4. Complete the session. Make a POST `/checkout_sessions/cs_test_abc123/complete` request. **Example request body object** ```json { "payment_data": { "provider": "adyen", "token": "" } } ``` Confirm that `status` is `completed` and `order.id` is present. ### Test product catalogue The Adyen test merchant exposes the following 10 products. Use these `id` values in the `items[]` array of any Create or Update Session request. Quantity must be ≥ 1. | Product ID | Name | Price | Category | | ---------- | ----------------- | ----- | ----------- | | `01` | **Polo shirt** | 50.00 | Clothing | | `02` | **Headphones** | 50.00 | Electronics | | `03` | **Sunglasses** | 50.00 | Accessories | | `04` | **Boots** | 50.00 | Footwear | | `05` | **Event ticket** | 50.00 | Tickets | | `06` | **Backpack** | 50.00 | Accessories | | `07` | **Joypad** | 50.00 | Electronics | | `08` | **Food delivery** | 50.00 | Food | | `09` | **Handbag** | 50.00 | Accessories | | `10` | **Sneakers** | 50.00 | Footwear | **Example object to create a session with a pair of Headphones and a Backpack** ```json { "items": [ { "id": "02", "quantity": 1 }, { "id": "06", "quantity": 1 } ] } ``` ## Sequence diagrams The two diagrams below show the full lifecycle for both integration patterns. In both cases your agent's calls to Adyen are identical — the difference is entirely in how Adyen and the merchant orchestrate payment authorization on the back end. #### Standard flow Adyen executes payment authorization on behalf of the agent. The agent's Token Vault calls `delegate_payment` to obtain a PSP token, which the agent then submits via `/complete`. Adyen handles the rest. ```mermaid sequenceDiagram participant Shopper participant Agent as AI Agent participant Vault as Token Vault participant Adyen participant Merchant rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 1. Create checkout Shopper->>Agent: "Buy these headphones" Agent->>Adyen: [ACP] POST /checkout_sessions Adyen->>Merchant: POST /agentic/sessions/{id} Merchant-->>Adyen: 200 status: totals, stock, shipping Adyen-->>Agent: 201: Session ID + totals Agent-->>Shopper: Display order summary end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 2. Delegate payment & tokenization Shopper->>Agent: "Pay now" Agent->>Vault: Instruct delegate_payment Vault->>Adyen: [ACP] /delegate_payment Adyen-->>Vault: psp_transaction_token Vault-->>Agent: psp_transaction_token end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 3. Complete & authorize Agent->>Adyen: [ACP] /checkout_sessions/{id}/complete Adyen->>Merchant: POST /agentic/sessions/{id}/commit Merchant-->>Adyen: 200 SUCCESS Note over Adyen: Execute Auth Adyen->>Merchant: POST /agentic/sessions/{id}/finalize Merchant-->>Adyen: 204 ACK: trigger fulfillment Adyen-->>Agent: 200 status: completed, order{} Agent-->>Shopper: "Order confirmed!" end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 4. Post-purchase Merchant->>Adyen: POST /events (tracking info) Adyen->>Agent: Push tracking to Agent Agent-->>Shopper: "Your package is on the way!" end ``` #### Advanced flow The agent's `/complete` call is identical to the standard flow. The difference: Adyen delivers the payment token to the merchant, who then calls `POST /payments` directly and triggers order fulfillment in a single synchronous step. ```mermaid sequenceDiagram participant Shopper participant Agent as AI Agent participant Vault as Token Vault participant Adyen participant Merchant rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 1. Create checkout Shopper->>Agent: "Buy these headphones" Agent->>Adyen: [ACP] POST /checkout_sessions Adyen->>Merchant: POST /agentic/sessions/{id} Merchant-->>Adyen: 200: totals, stock, shipping Adyen-->>Agent: 201: Session ID + totals Agent-->>Shopper: Display order summary end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 2. Delegate payment & tokenization Shopper->>Agent: "Pay now" Agent->>Vault: Instruct delegate_payment Vault->>Adyen: [ACP] /delegate_payment Adyen-->>Vault: psp_transaction_token Vault-->>Agent: psp_transaction_token end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 3. Complete & authorize (merchant-executed) Agent->>Adyen: [ACP] /checkout_sessions/{id}/complete Adyen->>Merchant: Payment token + session data Merchant->>Adyen: POST /payments (psp_token) Adyen-->>Merchant: Payment result (Authorised) Note over Merchant: Trigger fulfillment Merchant-->>Adyen: 204 ACK: payment result Adyen-->>Agent: 200 status: completed, order{} Agent-->>Shopper: "Order confirmed! Ref: ord_..." end rect rgb(245, 245, 245) Note over Shopper, Merchant: Stage 4. Post-purchase Merchant->>Adyen: POST /events (tracking info) Adyen->>Agent: Push tracking to Agent Agent-->>Shopper: "Your package is on the way!" end ``` ## Session statuses Every response contains a `status` field. Evaluate this field on every call. | Status | Category | Agent action | | ----------------------- | ------------ | --------------------------------------------------------------------------------------------------- | | `not_ready_for_payment` | Active | Session has blocking errors. Surface `messages[]` to the shopper and resolve before proceeding. | | `ready_for_payment` | Active | All data valid and totals confirmed. Prompt shopper to confirm, then call Complete Session. | | `in_progress` | Active | Session is actively being processed. Await the next status transition before taking further action. | | `completed` | **Terminal** | Payment authorized and order created. Present `order.permalink_url` and `order.id` to the shopper. | | `canceled` | **Terminal** | Session explicitly canceled. Do not reuse this session ID. | ## Error codes When the merchant rejects a request (HTTP `422`), the session response contains a `messages[]` array with structured error objects. Surface these to the shopper as appropriate. | HTTP | Reason code | Phase | Agent handling | | ---- | ----------------- | ------------------------ | -------------------------------------------------------------------------------------------------------- | | 200 | — | Any | Valid. Proceed to the next step. | | 422 | `OUT_OF_STOCK` | Create / Update / Commit | Item unavailable. Offer alternatives or remove from cart. | | 422 | `PARTIAL_STOCK` | Create / Update / Commit | Only X of Y units available. Offer reduced quantity. | | 422 | `INVALID_ADDRESS` | Create / Update / Commit | Delivery to this address unsupported. Prompt for alternative. | | 422 | `RISK_REJECTED` | Commit only | Merchant fraud engine blocked. Do not expose risk details. Offer alternative payment method. | | 422 | `PRICE_MISMATCH` | Commit only | Price changed since last fetch. Re-fetch session and present updated totals for shopper re-confirmation. | ### AcpMessage object All session responses include a required `messages[]` array. Each entry follows the `AcpMessage` schema. **AcpMessage example** ```json { "code": "OUT_OF_STOCK", "content": "The item is no longer available.", "content_type": "plain", "type": "error", "path": "items[0]" } ``` ## Schema Reference Endpoint: | Environment | Base URL | | ----------- | ------------------------------------------------------------------------------ | | Test | `https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{companyAccount}` | | Live | `https://commerce-suite.adyen.com/commerce-suite/acp/v1/{companyAccount}` | All request and response objects follow these standardized schemas. ### AcpItem | Parameter | Description | | ------------------------ | ------------------------------------- | | **`id`** *string* | Merchant's product or SKU identifier. | | **`quantity`** *integer* | Units requested. Must be ≥ 1. | ### AcpLineItem Returned in all session responses. Represents a resolved cart line with merchant-computed pricing. | Parameter | Description | | ----------------------------------- | -------------------------------------------------------------------------------------- | | **`id`** *string* | Unique identifier for this line item within the session. | | **`item`** *AcpItem* | The underlying item reference (`id` and `quantity`). | | **`base_amount`** *integer (int64)* | Pre-tax unit price × quantity in minor currency units, for example, `34900` = $349.00. | | **`discount`** *integer (int64)* | Discount applied to this line in minor currency units. `0` if no discount applies. | | **`subtotal`** *integer (int64)* | Line subtotal after any adjustments, before tax, in minor currency units. | | **`tax`** *integer (int64)* | Tax amount for this line in minor currency units. | | **`total`** *integer (int64)* | Final line total (subtotal + tax) in minor currency units. | ### AcpAddress | Parameter | Description | | ---------------------------------------- | --------------------------------------------------------------- | | **`line_one`** *string · max: 256* | Primary street address. | | **`line_two`** *string · max: 256* | Secondary address line (apartment, suite, unit). | | **`city`** *string · max: 256* | City name. | | **`state`** *string · min: 1* | State or province code. | | **`country`** *string · exactly 2 chars* | ISO 3166-1 alpha-2 country code, for example, `US`, `GB`, `NL`. | | **`postal_code`** *string · max: 20* | ZIP or postal code. | | **`name`** *string · max: 256* | Optional. Recipient name for the address. | ### AcpBuyer | Parameter | Description | | --------------------------- | ----------------------------- | | **`email`** *string* | Buyer's email address. | | **`first_name`** *string* | Buyer's first name. | | **`last_name`** *string* | Buyer's last name. | | **`phone_number`** *string* | Buyer's contact phone number. | ### AcpPaymentData | Parameter | Description | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **`provider`** *string · minLength: 1* | Payment provider identifier. Use `adyen` for Adyen-issued tokens. | | **`token`** *string · minLength: 1* | PSP transaction token from your vault's `delegate_payment` call. | | **`billing_address`** *AcpAddress* | Optional. Billing address associated with the payment instrument. If omitted, the `fulfillment_address` is used for billing. | ### AcpPaymentProvider Returned in Create Session response. | Parameter | Description | | ------------------------------------------- | ------------------------------------------------------------- | | **`provider`** *string* | Always "adyen" for this integration. | | **`merchant_id`** *string* | Adyen merchant account identifier for the connected merchant. | | **`supported_payment_methods`** *string\[]* | Accepted payment methods (e.g., \["scheme", "googlepay"]). | ### AcpFulfillmentOption (discriminated union) `AcpFulfillmentOption` is a discriminated union keyed on `type`. The base object only requires `type`. Use the subtype schemas based on the value of `type`. **Base** | Parameter | Description | | ------------------- | -------------------------------------------------------------------------------------------- | | **`type`** *string* | Discriminator field. Determines which subtype schema applies. Values: `shipping`, `digital`. | **AcpFulfillmentOptionShipping** (type: `shipping`) | Parameter | Description | | ------------------------------------------------- | -------------------------------------------------------------------------------- | | **`id`** *string* | Unique identifier. Pass as `fulfillment_option_id` in Update or Create Session. | | **`type`** *string* | Must be `shipping`. | | **`title`** *string* | Human-readable shipping option name. | | **`subtotal`** *integer (int64)* | Fulfillment subtotal before tax in minor currency units. | | **`tax`** *integer (int64)* | Tax on the fulfillment option in minor currency units. | | **`total`** *integer (int64)* | Total fulfillment cost (subtotal + tax) in minor currency units. | | **`carrier`** *string* | Optional. Carrier name, for example, `UPS`, `DHL`, `FedEx`. | | **`subtitle`** *string* | Optional. Additional description, for example, "Delivered in 5–7 business days". | | **`earliest_delivery_time`** *string (date-time)* | Optional. ISO 8601 timestamp for earliest expected delivery. | | **`latest_delivery_time`** *string (date-time)* | Optional. ISO 8601 timestamp for latest expected delivery. | **AcpFulfillmentOptionDigital** (type: `digital`) | Parameter | Description | | -------------------------------- | --------------------------------- | | **`id`** *string* | Unique identifier. | | **`type`** *string* | Must be `digital`. | | **`title`** *string* | Human-readable option name. | | **`subtotal`** *integer (int64)* | Fulfillment subtotal before tax. | | **`tax`** *integer (int64)* | Tax amount. | | **`total`** *integer (int64)* | Total cost (subtotal + tax). | | **`subtitle`** *string* | Optional. Additional description. | ### AcpTotal | Parameter | Description | | --------------------------- | -------------------------------------------------- | | **`type`** *string* | Total type (e.g., "subtotal", "tax", "total"). | | **`amount`** *integer* | Amount in minor currency units. | | **`display_text`** *string* | Localized label for display (e.g., "Order Total"). | ### AcpOrder Included in `AcpCompleteSessionResponse` when authorization succeeds. | Parameter | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------- | | **`id`** *string* | Unique order identifier. Present to the shopper as their order reference. | | **`checkout_session_id`** *string* | The originating checkout session ID for correlation. | | **`permalink_url`** *string* | Permanent URL to the merchant's order details page. Share with the shopper for tracking and support. | ### AcpMessage All responses include a required `messages[]` array. Evaluate it on every response, not only on error HTTP codes. | Parameter | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **`code`** *string* | Machine-readable reason code, for example, `OUT_OF_STOCK`, `PRICE_MISMATCH`, `INVALID_ADDRESS`, `RISK_REJECTED`. | | **`content`** *string* | Human-readable message text. Surface to the shopper when `type` is `error`. | | **`content_type`** *string* | Format of `content`. Either `plain` or `markdown`. | | **`type`** *string* | Message category. Either `error` (agent must act) or `info` (informational notice). | | **`path`** *string* | Optional. JSON path identifying the specific field that triggered the message, for example, `items[0]`. | ### AcpLink All session responses include a required `links[]` array of merchant policy and support URLs. | Parameter | Description | | ------------------- | ---------------------------------------------------------------------------------- | | **`type`** *string* | Link category, for example, `terms_of_service`, `return_policy`, `privacy_policy`. | | **`url`** *string* | The fully-qualified URL. | ### AcpUpdateCheckoutSessionRequest Dedicated schema for the Update Session endpoint. All fields are optional — include only what needs to change. | Parameter | Description | | ---------------------------------------------------- | ------------------------------------------------------ | | **`currency`** *string (ISO 4217) · exactly 3 chars* | Currency. Must match the session currency if provided. | | **`items`** *AcpItem\[]* | Replaces the entire item list. | | **`buyer`** *AcpBuyer* | Updated buyer contact information. | | **`fulfillment_address`** *AcpAddress* | Updated shipping address. | | **`fulfillment_option_id`** *string* | ID of the selected fulfillment option. | ### AcpAffiliateAttribution Optional affiliate attribution object for tracking referral sources at session creation. Include this to credit publishers, influencers, or campaign sources. | Parameter | Description | | -------------------------------------------- | --------------------------------------------------------------------------------------------------- | | **`provider`** *string · minLength: 1* | Attribution provider namespace identifier, for example, `impact.com`, `partnerize`. | | **`token`** *string* | Optional. Opaque provider-issued attribution token for fraud-resistant validation. | | **`publisher_id`** *string* | Optional. Provider-scoped affiliate or publisher identifier. | | **`campaign_id`** *string* | Optional. Provider-scoped campaign identifier. | | **`creative_id`** *string* | Optional. Provider-scoped creative identifier. | | **`sub_id`** *string* | Optional. Provider-scoped sub-tracking identifier. | | **`touchpoint`** *string (enum)* | Optional. Attribution touchpoint. Either `first` (session creation) or `last` (session completion). | | **`source`** *AcpAffiliateAttributionSource* | Optional. Context about where the attribution originated (`type` + optional `url`). | | **`issued_at`** *string (date-time)* | Optional. ISO 8601 timestamp when the attribution token was issued. | | **`expires_at`** *string (date-time)* | Optional. ISO 8601 timestamp when the attribution token expires. | | **`metadata`** *object* | Optional. Arbitrary key-value metadata for additional attribution context. |