--- title: "Agentic Cart API integration" description: "Enable AI agents to process payments through Adyen." url: "https://docs.adyen.com/online-payments/agentic-commerce/merchant/agentic-cart-api-integration" source_url: "https://docs.adyen.com/online-payments/agentic-commerce/merchant/agentic-cart-api-integration.md" canonical: "https://docs.adyen.com/online-payments/agentic-commerce/merchant/agentic-cart-api-integration" last_modified: "2025-12-23T10:11:00+01:00" language: "en" --- # Agentic Cart API integration Enable AI agents to process payments through Adyen. [View source](/online-payments/agentic-commerce/merchant/agentic-cart-api-integration.md) When a shopper uses an AI agent to make a purchase, the AI agent platform communicates with Adyen to initiate payments on behalf of shoppers. Adyen translates the information to be able to communicate with you. To enable Adyen to process payments for AI-agent-initiated transactions with you, you must create a server with endpoints that Adyen can make requests to. Adyen communicates with your server so that you do not need to integrate with multiple agent platforms. ## Requirements | Requirement | Description | | -------------------- | ------------------------------------------------------------ | | **Integration type** | An existing [online payments](/online-payments) integration. | ## How it works For this integration, your server must do the following: * Make requests to Adyen. * Expose endpoints that Adyen makes requests to. ### One-time configuration You must do a one-time configuration register your server's endpoints and declare which endpoints you want Adyen to make request to. ### Adyen requests to your server After you configure your server's endpoints, Adyen can make requests to them. You must set up your endpoints to do the following, so that Adyen can make requests to them: 1. [Create session](#create-session): Initialize a checkout session with items, shopper, and fulfillment details. 2. [Update session](#optional-update-session) (optional): Update items, address, or fulfillment selection and recalculate totals. 3. [Commit session](#optional-commit-session) (optional): Run a final price or stock check before Adyen authorizes the payment. 4. [Cancel session](#optional-cancel-session) (optional): Release reserved inventory when the shopper abandons checkout. 5. [Finalize session](#finalize-session): Receive the authorization result and trigger order creation. 6. [Complete session](#optional-complete-session-advanced-flow) (optional): Receive the payment token and make the payment request to Adyen directly. Response latency: Your server must respond to Adyen's requests within five seconds. Otherwise, we treat timeouts as errors. Possible flows: * [Standard](#sequence-diagrams): Adyen makes a request to finalize the session, and you fulfill the order. * [Advanced](#sequence-diagrams): We strongly recommend that you only use this flow if you must have direct control of the payment request. Adyen makes a request to complete the session and gives you a payment token. You make a payment request to Adyen. ### After purchase events After a purchase is finished, you can optionally send a request to Adyen to give order information to the agent (for example, shipping tracking). ## One-time configuration Register your server's base URL and declare which endpoints you want Adyen to make request to. You can update this configuration at any time without downtime. Use the following endpoint URL: | Environment | Endpoint URL | | ----------- | ---------------------------------------------------------------------------------------------------------- | | Test | `https://commerce-suite-test.adyen.com/commerce-suite/companies/v1/{CompanyAccount}/agentic/configuration` | | Live | `https://commerce-suite-live.adyen.com/commerce-suite/companies/v1/{CompanyAccount}/agentic/configuration` | Make a POST `/agentic/configuration` request, including the following parameters: Request headers: | Header | Description | | ----------------- | ------------------------------------------------------------------------------------------------- | | `x-api-key` | Your Adyen API key from your [Adyen company account](/account/account-structure#company-account). | | `Idempotency-Key` | A unique identifier for the request. | Request body: | Parameter | Type | Required | Description | | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `baseUrl` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your server's base URL. Adyen appends endpoint paths to this URL. For example: **your-agentic-server.example.com**. | | `security.apiKey` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The API key that Adyen includes in the `Authorization` header on every callback to your server. Validate it on every inbound request and reject anything that does not match. | | `features.enableCommitSession` | Boolean | | If **true**, Adyen makes a request to POST `/sessions/{sessionId}/commit` before authorizing. Use this to run a final price or stock check before the card is charged. Default: **false**. | | `features.enableCancelSession` | Boolean | | If **true**, Adyen makes a request to POST `/sessions/{sessionId}/cancel` when an agent cancels a session. Use this to release reserved inventory. Default: **false**. | | `features.enableFinalizeSession` | Boolean | | If **true**, Adyen makes a request to POST `/sessions/{sessionId}/finalize` after successful authorization. This is your fulfillment trigger. Default: **true**. | | `features.enableCompleteSession` | Boolean | | Advanced flow only. If **true**, Adyen makes a request to POST `/sessions/{sessionId}/complete` with the raw payment token. Your server makes a POST `/payments` request directly. Leave **false** unless you need to own the authorization step. Default: **false**. | **Example configuration request** ```bash curl -X POST https://commerce-suite-test.adyen.com/commerce-suite/agentic/configuration \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -H 'content-type: application/json' \ -d '{ "baseUrl": "https://api.testshop.com/adyen-integration", "features": { "enableCommitSession": false, "enableCancelSession": false, "enableFinalizeSession": true, "enableCompleteSession": false }, "security": { "apiKey": "API_KEY_FOR_VALIDATION" } }' ``` Never expose your `security.apiKey` in agent-readable context or client-side code. This key is your primary mechanism for confirming that a request originates from Adyen. ## Create session Set up the following endpoint: POST `/agentic/sessions/{sessionId}` Adyen makes a request to this endpoint when an AI agent initiates a new checkout session. This is the first request including the `sessionId` in the path. Your server must respond with authoritative totals, stock status, and available fulfillment options. Use the `sessionId` to create a draft order record in your system if needed. ## Adyen request to your server When Adyen makes a POST `/agentic/sessions/{sessionId}` request to your server, the request includes the following parameters: Path parameter: | Parameter | Description | | ----------- | --------------------------------------------------------------------------------------------------------- | | `sessionId` | The unique session identifier assign by Adyen. Use this to create or update a draft order in your system. | Request headers: | Header | Description | | --------------- | -------------------------------------------------------------------------------------- | | `Authorization` | Adyen-issued bearer token. Validate this token for every request your server receives. | Request body: | Parameter | Type | Required | Description | | ---------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `currency` | String ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The three-letter currency code, for example, **USD**, **EUR**, **GBP**. | | `lineItems` | [`MerchantItemRequest[]`](#merchantitemrequest) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Items requested by the agent. Each item requires an `id` and `quantity` of **1** or more. | | `shoppingPlatform` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Agent platform identifier, for example, **openai**, **google**, **meta**. | | `deliveryAddress` | [`MerchantAddress`](#merchantaddress) | | The shopper's delivery address. Required to compute shipping and address-level tax. | | `fulfillment` | [`MerchantFulfillment`](#merchantfulfillment) | | Contains `selectedFulfillmentOptionId` if the shopper has selected a shipping tier. | | `shopper` | [`MerchantShopper`](#merchantshopper) | | Shopper contact details: `email`, `firstName`, `lastName`, `phoneNumber`. | | `discounts` | [`MerchantDiscountsRequest`](#merchantdiscountsrequest) | | Discount codes submitted by the shopper. Validate and return applied or rejected results. | | `affiliateAttribution` | [`MerchantAffiliateAttribution`](#merchantaffiliateattribution) | | Affiliate attribution data passed through from the agent. | | `reference` | String | | Your internal reference for this session. Echo back in the response. | | `lineItems[].quantity` | Integer | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Units requested. Must be **1** or more. | | `lineItems[].id` | String | | Product or SKU identifier. Echo back in `MerchantLineItem.id`. | **Example request from Adyen to create session** ```bash curl -X POST https://your-agentic-server.example.com/agentic/sessions/cs_1abCd2Ef3GhIjK \ -H 'Authorization: Bearer ADYEN_SESSION_TOKEN' \ -H 'content-type: application/json' \ -d '{ "currency": "USD", "shoppingPlatform": "openai", "lineItems": [ { "id": "SKU-HEADPHONES-PRO", "quantity": 1 } ] }' ``` ## Your server response Build the responses that your server responds to Adyen with. The success HTTP **200** response includes the following. All fields are optional, but populate as much as possible because the agent presents these totals and options directly to the shopper. | Parameter | Type | Description | | ------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `merchantAccount` | String | Your Adyen merchant account identifier. Adyen uses this to route the payment. | | `reference` | String | Echo back the `reference` from the request. | | `lineItems` | Object\[] | Resolved line items with pricing, stock status, and discount breakdown. | | `lineItems[].quantity` | Integer | Resolved quantity for this line item. | | `lineItems[].id` | String | Echo back the product or SKU `id` from the request. | | `lineItems[].status` | String | Stock status: **IN\_STOCK**, **OUT\_OF\_STOCK**, or **PARTIAL\_STOCK**. | | `lineItems[].amount` | Object | Unit price multiplied by quantity in minor currency units. | | `lineItems[].discount` | Object | Discount applied to this line in minor currency units. | | `lineItems[].subtotal` | Object | Line subtotal after discount, before tax. | | `lineItems[].taxAmount` | Object | Tax for this line in minor currency units. | | `lineItems[].totalAmount` | Object | Final line total (subtotal + tax) in minor currency units. | | `fulfillmentOptions` | Object\[] | Available fulfillment options for the shopper to choose from. | | `fulfillmentOptions[].id` | String | Unique identifier. The shopper's selection is sent back as `fulfillment.selectedFulfillmentOptionId`. | | `fulfillmentOptions[].type` | String | Option type, for example, **shipping**, **digital**, **pickup**. | | `fulfillmentOptions[].title` | String | Human-readable name shown to the shopper, for example, **Express (1-2 days)**. | | `fulfillmentOptions[].subtitle` | String | Additional description, for example, **Delivered by FedEx**. | | `fulfillmentOptions[].carrier` | String | Carrier name, for example, **UPS**, **DHL**, **FedEx**. | | `fulfillmentOptions[].amount` | Object | Shipping cost before tax in minor currency units. | | `fulfillmentOptions[].taxAmount` | Object | Tax on this fulfillment option in minor currency units. | | `fulfillmentOptions[].total` | Object | Total fulfillment cost (`amount` + `taxAmount`) in minor currency units. | | `fulfillmentOptions[].earliestDeliveryTime` | String (date-time) | ISO 8601 timestamp for earliest expected delivery. | | `fulfillmentOptions[].latestDeliveryTime` | String (date-time) | ISO 8601 timestamp for latest expected delivery. | | `totals` | Object | Session totals. `totals.total.value` is the amount Adyen authorizes. | | `totals.subtotal` | Object | Order subtotal before tax and fulfillment. | | `totals.tax` | Object | Total tax for the order. | | `totals.fulfillment` | Object | Total fulfillment cost. | | `totals.total` | Object | Grand total (subtotal + tax + fulfillment). | | `discounts` | [MerchantDiscountsResponse](#merchantdiscountsresponse) | Discount processing results: applied and rejected codes with detail. | | `marketingConsentOptions` | Object\[] | Marketing consent channels to present to the shopper through the agent. | | `messages` | Object\[] | Structured messages. Include on all **422** responses. | | `messages[].code` | String | Machine-readable reason code aligned with `AgenticReasonCode`, for example, **OUT\_OF\_STOCK**. | | `messages[].content` | String | Human-readable message text. The agent shows this to the shopper when `type` is **ERROR**. | | `messages[].type` | String | **ERROR** blocks checkout. **INFO** is advisory and does not block. | | `links` | [MerchantLink](#merchantlink)\[] | Merchant policy URLs: terms of service, return policy, privacy policy. | | `reason` | String | Machine-readable rejection reason on **422** responses. See [Error handling and reason codes](#error-handling-and-reason-codes). | **Example success response (HTTP \*\*200\*\*)** ```json { "reference": "SESSION-2026-001", "merchantAccount": "ADYEN_MERCHANT_ACCOUNT", "lineItems": [ { "id": "SKU-HEADPHONES-PRO", "quantity": 1, "status": "IN_STOCK", "amount": { "value": 34900, "currency": "USD" }, "taxAmount": { "value": 3141, "currency": "USD" }, "totalAmount": { "value": 38041, "currency": "USD" } } ], "fulfillmentOptions": [ { "id": "ship_standard", "type": "shipping", "title": "Standard (5-7 days)", "carrier": "UPS", "amount": { "value": 999, "currency": "USD" }, "total": { "value": 999, "currency": "USD" } } ], "totals": { "subtotal": { "value": 34900, "currency": "USD" }, "tax": { "value": 3141, "currency": "USD" }, "fulfillment": { "value": 999, "currency": "USD" }, "total": { "value": 39040, "currency": "USD" } }, "messages": [], "links": [ { "type": "terms_of_service", "url": "https://www.your-shop.example.com/legal/terms-of-service" } ] } ``` **Example error response for an out-of-stock item (HTTP \*\*422\*\*)** ```json { "reason": "OUT_OF_STOCK", "lineItems": [ { "id": "SKU-HEADPHONES-PRO", "quantity": 1, "status": "OUT_OF_STOCK" } ], "messages": [ { "code": "OUT_OF_STOCK", "content": "This item is no longer available. Remove it from your cart.", "type": "ERROR" } ] } ``` ### Possible HTTP status codes | HTTP | `reason` | `lineItems.status` | Description | | ------- | -------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- | | **200** | None | **IN\_STOCK** | Session valid. Return `totals`, `lineItems`, and `fulfillmentOptions`. The agent presents these to the shopper. | | **422** | **OUT\_OF\_STOCK** | **OUT\_OF\_STOCK** | Requested items are fully unavailable. | | **422** | **PARTIAL\_STOCK** | **PARTIAL\_STOCK** | The number of available items is less than the requested number. | | **422** | **INVALID\_ADDRESS** | — | Shipping options do not support the delivery location. | ## (Optional) Update session Set up the following endpoint: POST `/agentic/sessions/{sessionId}` Adyen makes a request to this endpoint every time the cart changes after the initial create session request. This includes item quantity changes, delivery address updates, fulfillment option selection, or discount code application. The same endpoint path is used as [Create session](#create-session). Adyen distinguishes them by whether the `sessionId` already exists in your system. Handle duplicate update requests gracefully. Adyen may retry on timeout. Return the same response for the same session state. ### Adyen request to your server When Adyen makes a POST `/agentic/sessions/{sessionId}` request to your server, the request includes the following parameters. The schema is identical to [Create session](#create-session). On update requests, fields that have not changed can be omitted. Path parameter: | Parameter | Description | | ----------- | ------------------------------------------------ | | `sessionId` | The unique session identifier assigned by Adyen. | Request headers: | Header | Description | | --------------- | -------------------------------------------------------------------------------------- | | `Authorization` | Adyen-issued bearer token. Validate this token for every request your server receives. | Body parameters: | Parameter | Type | Description | | ---------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `currency` | String ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) | The three-letter currency code. Must match the session currency if provided. | | `lineItems` | Object\[] | Updated item list. Revalidate stock and recompute totals for all items. | | `lineItems[].quantity` | Integer | Units requested. Must be **1** or more. | | `lineItems[].id` | String | Product or SKU identifier. | | `shoppingPlatform` | String | Agent platform identifier. Usually unchanged from create. | | `deliveryAddress` | [MerchantAddress](#merchantaddress) | Updated delivery address. Triggers recalculation of shipping costs and tax. | | `fulfillment` | [MerchantFulfillment](#merchantfulfillment) | Updated fulfillment selection. Contains `selectedFulfillmentOptionId` chosen by the shopper. | | `shopper` | [MerchantShopper](#merchantshopper) | Updated shopper contact details. | | `discounts` | [MerchantDiscountsRequest](#merchantdiscountsrequest) | Discount codes to apply or update. | | `affiliateAttribution` | [MerchantAffiliateAttribution](#merchantaffiliateattribution) | Affiliate attribution data. | | `reference` | String | Session reference. | **Example request to update a session with address and fulfillment selection** ```bash curl -X POST https://your-agentic-server.example.com/agentic/sessions/cs_1abCd2Ef3GhIjK \ -H 'Authorization: Bearer ADYEN_SESSION_TOKEN' \ -H 'content-type: application/json' \ -d '{ "currency": "USD", "shoppingPlatform": "openai", "lineItems": [ { "id": "SKU-HEADPHONES-PRO", "quantity": 1 } ], "deliveryAddress": { "street": "123 Market St", "houseNumberOrName": "", "city": "San Francisco", "stateOrProvince": "CA", "country": "US", "postalCode": "94103" }, "fulfillment": { "selectedFulfillmentOptionId": "ship_express" } }' ``` **Example request to update a session with a discount code** ```bash curl -X POST https://your-agentic-server.example.com/agentic/sessions/cs_1abCd2Ef3GhIjK \ -H 'Authorization: Bearer ADYEN_SESSION_TOKEN' \ -H 'content-type: application/json' \ -d '{ "currency": "USD", "shoppingPlatform": "openai", "lineItems": [ { "id": "SKU-HEADPHONES-PRO", "quantity": 1 } ], "discounts": { "codes": ["SUMMER20"] } }' ``` ### Your server response The response schema is identical to [Create session](#your-server-response). Always return the fully recalculated state — never return only the changed fields. ### Possible HTTP status codes | HTTP | `reason` | `lineItems.status` | Description | | ------- | -------------------- | ------------------ | --------------------------------------------------------------------------------------------------- | | **200** | None | **IN\_STOCK** | Session updated. Return fully recalculated state. The agent presents updated totals to the shopper. | | **422** | **OUT\_OF\_STOCK** | **OUT\_OF\_STOCK** | Requested items are fully unavailable. | | **422** | **PARTIAL\_STOCK** | **PARTIAL\_STOCK** | The number of available items is less than the requested number. | | **422** | **INVALID\_ADDRESS** | — | Shipping options do not support the delivery location. | ## (Optional) Cancel session Set up the following endpoint: POST `/agentic/sessions/{sessionId}/cancel` Adyen makes a request to this endpoint when the shopper abandons checkout or the agent terminates the session before payment. Use this to release reserved inventory or discard draft orders. ### Adyen request to your server When Adyen makes a POST `/agentic/sessions/{sessionId}/cancel` request to your server, the request includes the following parameters: Path parameter: | Parameter | Description | | ----------- | ------------------------------------------------ | | `sessionId` | The unique session identifier assigned by Adyen. | Request headers: | Header | Description | | --------------- | -------------------------------------------------------------------------------------- | | `Authorization` | Adyen-issued bearer token. Validate this token for every request your server receives. | Body parameters: | Parameter | Type | Description | | ----------- | ------ | --------------------------------------------------------------------------------------------------------- | | `reference` | String | Session reference from the original create or update request. Use to locate your internal session record. | **Example request from Adyen to cancel a session** ```bash curl -X POST https://your-agentic-server.example.com/agentic/sessions/cs_1abCd2Ef3GhIjK/cancel \ -H 'Authorization: Bearer ADYEN_SESSION_TOKEN' \ -H 'content-type: application/json' \ -d '{ "reference": "SESSION-2026-001" }' ``` ### Your server response No response body is expected. Return the appropriate HTTP status code. ### Possible HTTP status codes | HTTP | Meaning | Description | | ------- | ---------- | ---------------------------------------------------------------------------- | | **204** | No Content | Session cancelled successfully. No response body expected. | | **409** | Conflict | Session cannot be cancelled. The session may already be in a terminal state. | ## (Optional) Commit session Set up the following endpoint: POST `/agentic/sessions/{sessionId}/commit` Adyen makes a request to this endpoint after the shopper confirms payment, but before Adyen executes authorization. Adyen sends the full session state and payment metadata. A **200** response is a binding commitment to fulfill the order at the stated totals — Adyen proceeds to authorization immediately after. This endpoint is only called if you set `features.enableCommitSession` to **true** in your [one-time configuration](#one-time-configuration). If disabled, Adyen proceeds directly to authorization after the final update session request. A **200** response is a commitment to fulfill the order at the stated totals. Adyen authorizes payment immediately after. Return **422** if you cannot guarantee fulfillment. ### Adyen request to your server When Adyen makes a POST `/agentic/sessions/{sessionId}/commit` request to your server, the request includes the following parameters: Path parameter: | Parameter | Description | | ----------- | ------------------------------------------------ | | `sessionId` | The unique session identifier assigned by Adyen. | Request headers: | Header | Description | | -------------------- | -------------------------------------------------------------------------------------- | | `Authorization` | Adyen-issued bearer token. Validate this token for every request your server receives. | | `X-Merchant-Account` | The Adyen merchant account for which this session was processed. | Body parameters: | Parameter | Type | Required | Description | | ------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `lineItems` | Object\[] | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Final resolved line items. | | `lineItems[].quantity` | Integer | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Resolved quantity for this line item. | | `lineItems[].id` | String | | Product or SKU identifier. | | `lineItems[].status` | String | | Stock status: **IN\_STOCK**, **OUT\_OF\_STOCK**, or **PARTIAL\_STOCK**. | | `lineItems[].totalAmount` | Object | | Final line total (subtotal + tax) in minor currency units. | | `billingAddress` | [MerchantAddress](#merchantaddress) | | The shopper's billing address at checkout completion. | | `fulfillmentOptions` | [MerchantFulfillment](#merchantfulfillment)\[] | | Selected fulfillment options. | | `totals` | Object | | Final session totals. Reconcile against your records — a mismatch should return **PRICE\_MISMATCH**. | | `totals.subtotal` | Object | | Order subtotal before tax and fulfillment. | | `totals.tax` | Object | | Total tax for the order. | | `totals.fulfillment` | Object | | Total fulfillment cost. | | `totals.total` | Object | | Grand total (subtotal + tax + fulfillment). | | `shopper` | [MerchantShopper](#merchantshopper) | | Final shopper details. | | `paymentMetadata` | Object | | Payment instrument metadata. Use for risk checks. | | `paymentMetadata.bin` | String | | Bank identification number (first 6 digits of the card). | | `paymentMetadata.cardAlias` | String | | Hashed card alias for velocity checks. | | `paymentMetadata.paymentMethod` | String | | Payment method type, for example, **visa**, **mc**, **amex**. | | `marketingConsents` | Object\[] | | Shopper's marketing consent choices at checkout. | | `messages` | Object\[] | | Any session messages. | | `links` | [MerchantLink](#merchantlink)\[] | | Merchant policy links from the session. | | `reference` | String | | Session reference. | **Example request from Adyen to commit a session** ```bash curl -X POST https://your-agentic-server.example.com/agentic/sessions/cs_8xzQk2TmNpR/commit \ -H 'Authorization: Bearer ADYEN_SESSION_TOKEN' \ -H 'X-Merchant-Account: ADYEN_MERCHANT_ACCOUNT' \ -H 'content-type: application/json' \ -d '{ "lineItems": [ { "id": "SKU-HEADPHONES-PRO", "quantity": 1, "status": "IN_STOCK", "totalAmount": { "value": 38041, "currency": "USD" } } ], "totals": { "subtotal": { "value": 34900, "currency": "USD" }, "tax": { "value": 3141, "currency": "USD" }, "fulfillment": { "value": 999, "currency": "USD" }, "total": { "value": 39040, "currency": "USD" } }, "paymentMetadata": { "bin": "411111", "paymentMethod": "visa" } }' ``` ### Your server response The success HTTP **200** response includes the following: | Parameter | Type | Required | Description | | ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `lineItems` | Object\[] | | Updated line items if stock or pricing changed during commit. | | `messages` | Object\[] | | Structured messages. Errors block authorization. | | `order` | Object | | If you pre-create the order at this point, return it here. | | `order.id` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your unique order identifier. | | `order.checkoutSessionId` | String | | The originating checkout `sessionId`. | | `order.permalinkUrl` | String | | Permanent URL to your order details page. The agent presents this to the shopper as their confirmation link. | | `reason` | String | | Machine-readable rejection reason on **422** responses. See [Error handling and reason codes](#error-handling-and-reason-codes). | ### Possible HTTP status codes | HTTP | `reason` | `lineItems.status` | Description | | ------- | ------------------- | ------------------ | --------------------------------------------------------------------- | | **200** | None | **IN\_STOCK** | Commit accepted. Adyen proceeds to payment authorization immediately. | | **422** | **OUT\_OF\_STOCK** | **OUT\_OF\_STOCK** | Requested items are fully unavailable. | | **422** | **PARTIAL\_STOCK** | **PARTIAL\_STOCK** | The number of available items is less than the requested number. | | **422** | **PRICE\_MISMATCH** | — | Totals do not match your records. | ## Finalize session Set up the following endpoint: POST `/agentic/sessions/{sessionId}/finalize` Adyen makes a request to this endpoint after successful authorization. This is the signal to create the final order and begin fulfillment. If you already consume standard Adyen webhook messages with `eventCode`: **AUTHORISATION**, you can use those instead of this endpoint. The webhook message includes the same authorization result and additional agentic metadata including `sessionId` and `shoppingPlatform` in `additionalData`. Configure your preference in your [one-time configuration](#one-time-configuration). ### Adyen request to your server When Adyen makes a POST `/agentic/sessions/{sessionId}/finalize` request to your server, the request includes the following parameters: Path parameter: | Parameter | Description | | ----------- | ------------------------------------------------ | | `sessionId` | The unique session identifier assigned by Adyen. | Request headers: | Header | Description | | -------------------- | -------------------------------------------------------------------------------------- | | `Authorization` | Adyen-issued bearer token. Validate this token for every request your server receives. | | `X-Merchant-Account` | The Adyen merchant account for which this session was processed. | Body parameters: | Parameter | Type | Required | Description | | ------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `lineItems` | Object\[] | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Final authorized line items. | | `lineItems[].quantity` | Integer | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Resolved quantity for this line item. | | `lineItems[].id` | String | | Product or SKU identifier. | | `lineItems[].status` | String | | Stock status: **IN\_STOCK**, **OUT\_OF\_STOCK**, or **PARTIAL\_STOCK**. | | `lineItems[].amount` | Object | | Unit price multiplied by quantity in minor currency units. | | `lineItems[].taxAmount` | Object | | Tax for this line in minor currency units. | | `lineItems[].totalAmount` | Object | | Final line total (subtotal + tax) in minor currency units. | | `billingAddress` | [MerchantAddress](#merchantaddress) | | The shopper's billing address associated with the authorized payment. | | `fulfillmentOptions` | Object\[] | | Selected fulfillment methods for this order. | | `fulfillmentOptions[].id` | String | | Unique identifier for the fulfillment option. | | `fulfillmentOptions[].type` | String | | Option type, for example, **shipping**, **digital**, **pickup**. | | `fulfillmentOptions[].title` | String | | Human-readable name shown to the shopper. | | `fulfillmentOptions[].carrier` | String | | Carrier name, for example, **UPS**, **DHL**, **FedEx**. | | `fulfillmentOptions[].amount` | Object | | Shipping cost before tax in minor currency units. | | `totals` | Object | | Final authorized totals. Use these to create your order record. | | `totals.subtotal` | Object | | Order subtotal before tax and fulfillment. | | `totals.tax` | Object | | Total tax for the order. | | `totals.fulfillment` | Object | | Total fulfillment cost. | | `totals.total` | Object | | Grand total (subtotal + tax + fulfillment). | | `shopper` | [MerchantShopper](#merchantshopper) | | Shopper contact details. | | `paymentMetadata` | Object | | Payment instrument metadata. | | `paymentMetadata.paymentMethod` | String | | Payment method used, for example, **visa**, **mc**. | | `paymentMetadata.bin` | String | | Bank identification number (first 6 digits of the card). | | `paymentMetadata.cardAlias` | String | | Tokenized card alias. | | `messages` | Object\[] | | Any session messages. | | `links` | [MerchantLink](#merchantlink)\[] | | Merchant policy links from the session. | | `reference` | String | | Session reference. | **Example request from Adyen to finalize a session** ```bash curl -X POST https://your-agentic-server.example.com/agentic/sessions/cs_1abCd2Ef3GhIjK/finalize \ -H 'Authorization: Bearer ADYEN_SESSION_TOKEN' \ -H 'X-Merchant-Account: ADYEN_MERCHANT_ACCOUNT' \ -H 'content-type: application/json' \ -d '{ "lineItems": [ { "id": "SKU-HEADPHONES-PRO", "quantity": 1, "status": "IN_STOCK", "amount": { "value": 34900, "currency": "USD" }, "taxAmount": { "value": 3141, "currency": "USD" }, "totalAmount": { "value": 38041, "currency": "USD" } } ], "totals": { "subtotal": { "value": 34900, "currency": "USD" }, "fulfillment": { "value": 999, "currency": "USD" }, "tax": { "value": 3141, "currency": "USD" }, "total": { "value": 39040, "currency": "USD" } }, "fulfillmentOptions": [ { "id": "ship_standard", "type": "shipping", "title": "Standard (5-7 days)", "carrier": "UPS", "amount": { "value": 999, "currency": "USD" } } ], "paymentMetadata": { "paymentMethod": "visa", "bin": "411111", "cardAlias": "alias_ABCD1234" }, "reference": "SESSION-2026-001" }' ``` ### Your server response No response body is expected. Return the appropriate HTTP status code. ### Possible HTTP status codes | HTTP | Meaning | Description | | ------- | ---------- | ------------------------------------------------------------------------------- | | **204** | No Content | Finalization acknowledged. Create the final order record and begin fulfillment. | ## (Optional) Complete session (advanced flow) Set up the following endpoint: POST `/agentic/sessions/{sessionId}/complete` If you implement the advanced flow, Adyen makes a request to this endpoint instead of the [finalize session](#finalize-session) one. Adyen sends the raw payment token, and your server executes payment authorization directly with a POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request and handles fulfillment synchronously in one step. ### Adyen request to your server When Adyen makes a POST `/agentic/sessions/{sessionId}/complete` request to your server, the request includes the following parameters: Path parameter: | Parameter | Description | | ----------- | ------------------------------------------------ | | `sessionId` | The unique session identifier assigned by Adyen. | Request headers: | Header | Description | | --------------- | -------------------------------------------------------------------------------------- | | `Authorization` | Adyen-issued bearer token. Validate this token for every request your server receives. | Body parameters: | Parameter | Type | Required | Description | | ----------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paymentData` | Object | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The payment token. Pass `paymentData.token` as `paymentMethod.storedPaymentMethodId` in your POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. | | `paymentData.provider` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Payment provider. Always **adyen** for this integration. | | `paymentData.token` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The ACP token from Adyen. Pass as `paymentMethod.storedPaymentMethodId` in your POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. | | `lineItems` | Object\[] | | Final resolved line items. | | `lineItems[].quantity` | Integer | | Resolved quantity for this line item. | | `lineItems[].id` | String | | Product or SKU identifier. | | `lineItems[].status` | String | | Stock status: **IN\_STOCK**, **OUT\_OF\_STOCK**, or **PARTIAL\_STOCK**. | | `lineItems[].amount` | Object | | Unit price multiplied by quantity in minor currency units. | | `lineItems[].taxAmount` | Object | | Tax for this line in minor currency units. | | `lineItems[].totalAmount` | Object | | Final line total (subtotal + tax) in minor currency units. | | `totals` | Object | | Final totals. Use `totals.total.value` and `totals.total.currency` as the `amount` in your `POST` [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. | | `totals.subtotal` | Object | | Order subtotal before tax and fulfillment. | | `totals.tax` | Object | | Total tax for the order. | | `totals.fulfillment` | Object | | Total fulfillment cost. | | `totals.total` | Object | | Grand total (subtotal + tax + fulfillment). | | `selectedFulfillmentOptionId` | String | | The fulfillment option the shopper selected. | | `billingAddress` | [MerchantAddress](#merchantaddress) | | The shopper's billing address. | | `shopper` | [MerchantShopper](#merchantshopper) | | Shopper contact details. | | `marketingConsents` | [MerchantMarketingConsent](#merchantmarketingconsent)\[] | | The shopper's marketing opt-in or opt-out choices. | | `affiliateAttribution` | [MerchantAffiliateAttribution](#merchantaffiliateattribution) | | Attribution data for tracking. | | `reference` | String | | Session reference. | **Example request from Adyen to complete a session** ```bash curl -X POST https://your-agentic-server.example.com/agentic/sessions/cs_1abCd2Ef3GhIjK/complete \ -H 'Authorization: Bearer ADYEN_SESSION_TOKEN' \ -H 'content-type: application/json' \ -d '{ "paymentData": { "provider": "adyen", "token": "PAYMENT_TOKEN_FROM_ADYEN" }, "lineItems": [ { "id": "SKU-HEADPHONES-PRO", "quantity": 1, "status": "IN_STOCK", "amount": { "value": 34900, "currency": "USD" }, "taxAmount": { "value": 3141, "currency": "USD" }, "totalAmount": { "value": 38041, "currency": "USD" } } ], "totals": { "subtotal": { "value": 34900, "currency": "USD" }, "fulfillment": { "value": 999, "currency": "USD" }, "tax": { "value": 3141, "currency": "USD" }, "total": { "value": 39040, "currency": "USD" } }, "selectedFulfillmentOptionId": "ship_standard", "reference": "SESSION-2026-001" }' ``` 1. Get the information that you need to [make a payment request to Adyen](#payment-request-to-adyen). ### Your server response The success HTTP **200** response includes the following: | Parameter | Type | Description | | ------------------------- | --------- | ----------------------------------------------------------------- | | `order` | Object | The order you created. | | `order.id` | String | Your internal order identifier. | | `order.checkoutSessionId` | String | The `sessionId` path parameter. | | `order.permalinkUrl` | String | The URL where the shopper can view the order. | | `lineItems` | Object\[] | Final line items for the order. | | `messages` | Object\[] | Any messages to surface. | | `reason` | String | Machine-readable failure reason if payment or fulfillment failed. | ### Possible HTTP status codes | HTTP | `reason` | `lineItems.status` | Description | | ------- | ------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **200** | None | **IN\_STOCK** | Payment executed and order created. Return the response with the `order` object. | | **422** | **PAYMENT\_FAILED** | — | The payment was not successfully authorized. The POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response included an unsuccessful authorization result. | ### Make the payment request to Adyen 2. Make a POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, including the information from Adyen's request to your server: | Parameter in payment request | Value | | ------------------------------------- | --------------------------------------- | | `paymentMethod.storedPaymentMethodId` | The value from `paymentData.token`. | | `shopperReference` | The `sessionId` path parameter. | | `merchantAccount` | Your Adyen merchant account. | | `amount.value` | The value from `totals.total.value`. | | `amount.currency` | The value from `totals.total.currency`. | | `shopperInteraction` | **ContAuth** | | `recurringProcessingModel` | **UnscheduledCardOnFile** | | `reference` | Your internal order reference. | ## (Optional) Events after the purchase Make a request to: POST `https://commerce-suite-test.adyen.com/commerce-suite/companies/v1/{CompanyAccount}/agentic/sessions/{sessionId}/events` After the purchase, you can send fulfillment updates to Adyen. The AI agent uses these to support the shopper with post-purchase questions, for example, "What is the status of my order?". ### Your request to Adyen Path parameters: | Parameter | Description | | ---------------- | ------------------------------------------------ | | `CompanyAccount` | Your Adyen company account. | | `sessionId` | The unique session identifier assigned by Adyen. | Request headers: | Header | Description | | --------------- | -------------------------------------------------------------------------------------- | | `Authorization` | Adyen-issued bearer token. Validate this token for every request your server receives. | Request body: | Parameter | Type | Required | Description | | ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `eventCode` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The type of event. For example, **ORDER\_SHIPPED**. | | `payload` | Object | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Event details. | | `payload.carrier` | String | | Carrier name, for example, **Example Carrier**. | | `payload.trackingNumber` | String | | Carrier tracking number. | | `payload.trackingUrl` | String | | URL for the shopper to track their shipment. | **Example event request** ```bash curl -X POST https://commerce-suite-test.adyen.com/commerce-suite/companies/v1/YOUR_COMPANY_ACCOUNT/agentic/sessions/cs_1abCd2Ef3GhIjK/events \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \ -H 'content-type: application/json' \ -d '{ "eventCode": "ORDER_SHIPPED", "payload": { "carrier": "Example Carrier", "trackingNumber": "carrier_abcd_1234", "trackingUrl": "https://carrier.example.com/track/carrier_abcd_1234" } }' ``` ### Adyen response No response body is expected. You get an HTTP **204** acknowledgment. ## Test and go live Use the Adyen sandbox to test your server's endpoints end-to-end before going live. The sandbox makes requests to your endpoints exactly like in the live environment. ### Recommended test sequence To verify your integration, follow these steps: 1. Register your test endpoints. Make a POST `https://commerce-suite-test.adyen.com/commerce-suite/companies/v1/{CompanyAccount}/agentic/configuration` request with your test base URL and enable the endpoints you want to test. 2. Trigger a create session request. Adyen makes a POST `/agentic/sessions/{sessionId}` request. Your server responds with `lineItems`, `fulfillmentOptions`, and `totals`. 3. Test an update with address and fulfillment selection. Adyen makes a POST `/agentic/sessions/{sessionId}` request with an updated body. Confirm that your server returns recalculated totals. 4. Test stock error handling. Return a **422** response with `reason`: **OUT\_OF\_STOCK** and `messages[]`. 5. Test commit (if enabled). Adyen makes a POST `/agentic/sessions/{sessionId}/commit` request. Your server responds with **200 OK** to accept, or **422** with `reason`: **RISK\_REJECTED** to reject. 6. Test finalize. Adyen makes a POST `/agentic/sessions/{sessionId}/finalize` request. Your server responds with **204 No Content**. Verify that the order is created in your system. ## Go live 1. Before you go live, verify the following: * You tested your integration end-to-end, including error scenarios. * Your server validates the `Authorization` header from each inbound request from Adyen. * Your server's endpoints respond within five seconds, under the load of the expected volume of requests in the live environment. * Your server's [create session](#create-session) and [update session](#update-session) endpoints return **200** with the following: * `lineItems` * `fulfillmentOptions` * `totals` * Your server's [commit-session](#commit-session) endpoint validates the `X-Merchant-Account` header in the request. * Your server's [finalize session](#finalize-session) endpoint: * Validadtes the `X-Merchant-Account` header in the request. * Returns **204 No Content** (no response body). * Your server's [cancel session](#cancel-session) endpoint returns: * **204**: For a successful request. * **409**: If the session cannot be cancelled. * For each **422** response from your server: * The response body includes the following `MerchantMessage` parameters: * `code` * `content` * `type` * The response body includes the `AgenticReasonCode` object. * Your server's [complete session](#complete-session) endpoint (advanced flow): * Includes an `order.permalinkUrl` that is a stable and publicly accessible. * The `marketingConsents` object applies to shopper preferences is stored in a [persistent](https://en.wikipedia.org/wiki/Persistence_\(computer_science\)) way. * The `affiliateAttribution` data is stored for reporting. 2. Make the one-time configuration request to Adyen, using the live endpoint URL: `https://commerce-suite-live.adyen.com/commerce-suite/companies/v1/{CompanyAccount}/agentic/configuration`. ## Sequence diagrams Standard flow (ACP): ```mermaid sequenceDiagram participant S as Shopper participant A as AI agent participant V as Agent's token vault participant P as Adyen participant M as Your server Note over S, M: Checkout creation S ->> A: Message: "I want to buy these headphones" A ->> P: /checkout_session P ->> M: POST /agentic/sessions/{sessionId} M -->> P: HTTP 200 response with body including totals, shipping, and inventory info P -->> A: sessionId and order information A -->> S: Show order info (like price and inventory) Note over S, M: Payment and final validation S ->> A: "Pay now" A ->> V: Instruct to delegate payment for the session V ->> P: /delegate_payment with secure data P -->> V: Return unique transaction token V -->> A: Return transaction token Note over S, M: Commit, authorize, and finalize A ->> P: POST /checkout_session/{sessionId}/complete including unique transaction token P ->> M: POST/agentic/sessions/{id}/commit M -->> P: HTTP 200 response P ->> P: Execute payment authorization P ->> M: POST /agentic/sessions/{sessionId}/finalize M -->> P: HTTP 200 response M ->> M: Trigger order creation P -->> A: Return final status: SUCCESS A -->> S: "Order confirmed. Reference: UNIQUE_ORDER_REF" Note over S, M: After the purchase M ->> P: POST /agentic/sessions/{sessionId}/events with tracking information P ->> A: Send tracking information A -->> S: "Your package is on the way! Tracking link: SHIPPING_TRACKING_URL" ``` Advanced flow (ACP): ```mermaid sequenceDiagram participant S as Shopper participant A as AI agent participant V as Agent's token vault participant P as Adyen participant M as Your server Note over S, M: Checkout creation S ->> A: Message: "I want to buy these headphones" A ->> P: /checkout_session P ->> M: POST /agentic/sessions/{sessionId} M -->> P: HTTP 200 response with body including totals, shipping, and inventory info P -->> A: sessionId and order information A -->> S: Show order info (like price and inventory) Note over S, M: Payment and final validation S ->> A: "Pay now" A ->> V: Instruct to delegate payment for the session V ->> P: /delegate_payment with secure data P -->> V: Return unique transaction token V -->> A: Return transaction token Note over S, M: Complete (merchant-executed payment) A ->> P: POST /checkout_session/{sessionId}/complete including unique transaction token P ->> M: POST /agentic/sessions/{sessionId}/complete with transaction token M ->> P: POST /payments with transaction token P -->> M: Return payment result (successful authorization) M ->> M: Trigger order creation M -->> P: Return payment result P -->> A: Return final status: SUCCESS A -->> S: "Order confirmed. Reference: UNIQUE_ORDER_REF" Note over S, M: After the purchase M ->> P: POST /agentic/sessions/{sessionId}/events with tracking information P ->> A: Send tracking information A -->> S: "Your package is on the way! Tracking link: SHIPPING_TRACKING_URL" ``` Standard flow (UCP): ```mermaid sequenceDiagram participant S as Shopper participant A as AI agent participant V as Agent's token vault participant P as Adyen participant M as Your server Note over S, M: Checkout creation S ->> A: Message: "I want to buy these headphones" A ->> P: POST /checkout (line_items, buyer) P ->> M: POST /agentic/sessions/{sessionId} M -->> P: HTTP 200 response with body including totals and shipping info P -->> A: UCP checkout object A -->> S: Show order info Note over S, M: Tokenization and completion S ->> A: "Pay now" A ->> V: Retrieve raw payment credentials V -->> A: Secure card data A ->> P: POST /checkout/{sessionId}/complete with UCP token P ->> V: POST /detokenize with UCP token V -->> P: Card details Note over S, M: Commit, authorize, and finalize P ->> M: POST /agentic/sessions/{sessionId}/commit M -->> P: HTTP 200 response P ->> P: Execute payment authorization P ->> M: POST /agentic/sessions/{sessionId}/finalize M ->> M: Trigger order creation P -->> A: UCP checkout object (status: completed) A -->> S: "Order confirmed. Reference: UNIQUE_ORDER_REF" Note over S, M: After the purchase M ->> P: POST /agentic/sessions/{sessionId}/events with tracking information P ->> A: Send tracking information A -->> S: "Your package is on the way! Tracking link: SHIPPING_TRACKING_URL" ``` ## Schema reference The following shows the objects used in the request and response bodies. ### MerchantItemRequest | Parameter | Type | Required | Description | | ---------- | ------- | -------- | --------------------------------------- | | `id` | String | | Product or SKU identifier. | | `quantity` | Integer | | Units requested. Must be **1** or more. | ### MerchantAddress | Parameter | Type | Required | Description | | ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- | | `street` | String | | Primary street name. | | `houseNumberOrName` | String | | House number or building name. | | `city` | String | | City name. | | `stateOrProvince` | String | | State or province code ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)). | | `country` | String | | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, for example, **US**, **GB**, **NL**. | | `postalCode` | String | | ZIP or postal code. | ### MerchantShopper | Parameter | Type | Required | Description | | ------------- | ------ | -------- | ---------------------------- | | `email` | String | | The shopper's email address. | | `firstName` | String | | The shopper's first name. | | `lastName` | String | | The shopper's last name. | | `phoneNumber` | String | | The shopper's phone number. | ### MerchantFulfillment | Parameter | Type | Required | Description | | ----------------------------- | ------ | -------- | -------------------------------------------------------- | | `selectedFulfillmentOptionId` | String | | The `id` of the fulfillment option the shopper selected. | ### MerchantDiscountsRequest | Parameter | Type | Required | Description | | --------- | --------- | -------- | ------------------------------------------------- | | `codes` | String\[] | | Discount or promo codes submitted by the shopper. | ### MerchantDiscountsResponse | Parameter | Type | Required | Description | | ---------- | --------------------------------------------------------- | -------- | -------------------------------- | | `codes` | String\[] | | All submitted codes echoed back. | | `applied` | [MerchantAppliedDiscount\[\]](#merchantapplieddiscount) | | Successfully applied discounts. | | `rejected` | [MerchantRejectedDiscount\[\]](#merchantrejecteddiscount) | | Rejected codes with reason. | ### MerchantAppliedDiscount | Parameter | Type | Required | Description | | ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `id` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Unique identifier for this applied discount. | | `amount` | Integer (int64) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Total discount amount in minor currency units. | | `coupon` | [MerchantCoupon](#merchantcoupon) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The coupon definition. | | `code` | String | | The discount code string. | | `automatic` | Boolean | | **true** if applied automatically without a code. | | `method` | String | | How the discount is allocated: **each** (per line item) or **across** (proportional). | | `allocations` | [MerchantDiscountAllocation\[\]](#merchantdiscountallocation) | | Per-line-item breakdown. Each entry has `path` (JSON pointer) and `amount`. | | `start` | String (date-time) | | Discount validity start. | | `end` | String (date-time) | | Discount validity end. | ### MerchantDiscountAllocation | Parameter | Type | Required | Description | | --------- | --------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `amount` | Integer (int64) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Discount amount allocated to this line item in minor currency units. | | `path` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | JSON pointer to the line item, for example, **/lineItems/0**. | ### MerchantRejectedDiscount | Parameter | Type | Required | Description | | --------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `code` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The discount code that was rejected. | | `reason` | [MerchantDiscountErrorCode](#merchantdiscounterrorcode) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Machine-readable rejection reason. | | `message` | String | | Human-readable explanation. Surface this to the shopper. | ### MerchantDiscountErrorCode | Value | Description | | ------------------------------------------- | --------------------------------------------------------------- | | **discount\_code\_expired** | The discount code has passed its expiry date. | | **discount\_code\_invalid** | The code does not exist or is malformed. | | **discount\_code\_already\_applied** | This code has already been applied to the session. | | **discount\_code\_combination\_disallowed** | This code cannot be combined with other active discounts. | | **discount\_code\_minimum\_not\_met** | Cart total does not meet the minimum order value for this code. | | **discount\_code\_user\_not\_logged\_in** | Code requires the shopper to be authenticated. | | **discount\_code\_user\_ineligible** | The shopper does not qualify for this discount. | | **discount\_code\_usage\_limit\_reached** | Maximum redemption count has been reached. | ### MerchantCoupon | Parameter | Type | Required | Description | | ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `id` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Unique coupon identifier. | | `name` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Human-readable coupon name. | | `percentOff` | Integer (int32) | | Percentage discount (0–100). | | `amountOff` | Integer (int64) | | Fixed discount amount in minor currency units. | | `currency` | String | | Currency of `amountOff` ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)). | | `duration` | String | | **once**, **repeating**, or **forever**. | | `durationInMonths` | Integer (int32) | | Number of months when `duration` is **repeating**. | | `maxRedemptions` | Integer (int32) | | Maximum redemption count. | | `timesRedeemed` | Integer (int32) | | How many times this coupon has been redeemed. | | `metadata` | Object | | Arbitrary string key-value metadata. | ### MerchantMarketingConsent | Parameter | Type | Required | Description | | --------- | ------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `channel` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Marketing channel, for example, **email**, **sms**, **push**. | | `optedIn` | Boolean | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The shopper's consent decision. **true** = opted in; **false** = opted out. | ### MerchantMarketingConsentOption Return these in your session response to surface consent options to the shopper through the agent. | Parameter | Type | Required | Description | | ------------------ | ------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `channel` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Channel identifier, for example, **email**, **sms**. | | `displayText` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Localized consent prompt to show to the shopper. | | `privacyPolicyUrl` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | URL to your privacy policy for this channel. | | `isSubscribed` | Boolean | | Pre-populated subscription state for returning shoppers. | ### MerchantAffiliateAttribution | Parameter | Type | Required | Description | | ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `provider` | String | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Attribution provider identifier, for example, **impact.com**. | | `token` | String | | Provider-issued attribution token. | | `publisherId` | String | | Affiliate or publisher identifier. | | `campaignId` | String | | Campaign identifier. | | `creativeId` | String | | Creative identifier. | | `subId` | String | | Sub-tracking identifier. | | `touchpoint` | String | | Attribution touchpoint: **first** (session create) or **last** (session complete). | | `source` | Object | | Source context. Required field: `type` (**url**, **platform**, or **unknown**). Optional: `url`. | | `issuedAt` | String (date-time) | | When the attribution token was issued. | | `expiresAt` | String (date-time) | | When the attribution token expires. | | `metadata` | Object | | Arbitrary key-value metadata. | ### MerchantLink | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------------------------------------------------------- | | `type` | String | | Link category, for example, **terms\_of\_service**, **return\_policy**, **privacy\_policy**. | | `url` | String | | Fully qualified URL. |