AI agent integration with Agentic Commerce Suite

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

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.

The agentic commerce checkout lifecycle consists of up to five phases.

See 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.

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		3-letter settlement currency code, for example, USD, EUR, GBP.
items	AcpItem[]		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.

Response

Identical to AcpCheckoutSessionResponse plus a required payment_provider object.

Status codes

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		Your Adyen company account identifier.
sessionId	string		The id returned from the Create Session call.

Status codes

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.

Status codes

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

Success response

Status codes

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

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:

https://commerce-suite-test.adyen.com/commerce-suite/acp/v1/{companyAccount}

Sandbox endpoints

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.

   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.

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.

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.

Session statuses

Every response contains a status field. Evaluate this field on every call.

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.

AcpMessage object

All session responses include a required messages[] array. Each entry follows the AcpMessage schema.

Schema Reference

Endpoint:

All request and response objects follow these standardized schemas.

AcpItem

AcpLineItem

Returned in all session responses. Represents a resolved cart line with merchant-computed pricing.

AcpAddress

AcpBuyer

AcpPaymentData

AcpPaymentProvider

Returned in Create Session response.

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

AcpFulfillmentOptionShipping (type: shipping)

AcpFulfillmentOptionDigital (type: digital)

AcpTotal

AcpOrder

Included in AcpCompleteSessionResponse when authorization succeeds.

AcpMessage

All responses include a required messages[] array. Evaluate it on every response, not only on error HTTP codes.

AcpLink

All session responses include a required links[] array of merchant policy and support URLs.

AcpUpdateCheckoutSessionRequest

Dedicated schema for the Update Session endpoint. All fields are optional — include only what needs to change.

AcpAffiliateAttribution

Optional affiliate attribution object for tracking referral sources at session creation. Include this to credit publishers, influencers, or campaign sources.