Agentic Cart API integration

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

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: Initialize a checkout session with items, shopper, and fulfillment details.
2. Update session (optional): Update items, address, or fulfillment selection and recalculate totals.
3. Commit session (optional): Run a final price or stock check before Adyen authorizes the payment.
4. Cancel session (optional): Release reserved inventory when the shopper abandons checkout.
5. Finalize session: Receive the authorization result and trigger order creation.
6. Complete session (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: Adyen makes a request to finalize the session, and you fulfill the order.
• Advanced: 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:

Make a POST /agentic/configuration request, including the following parameters:

Request headers:

Request body:

Parameter	Type	Required	Description
baseUrl	String		Your server's base URL. Adyen appends endpoint paths to this URL. For example: your-agentic-server.example.com.
security.apiKey	String		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.

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:

Request headers:

Request body:

Parameter	Type	Required	Description
currency	String (ISO 4217)		The three-letter currency code, for example, USD, EUR, GBP.
lineItems	MerchantItemRequest[]		Items requested by the agent. Each item requires an id and quantity of 1 or more.
shoppingPlatform	String		Agent platform identifier, for example, openai, google, meta.
deliveryAddress	MerchantAddress		The shopper's delivery address. Required to compute shipping and address-level tax.
fulfillment	MerchantFulfillment		Contains selectedFulfillmentOptionId if the shopper has selected a shipping tier.
shopper	MerchantShopper		Shopper contact details: email, firstName, lastName, phoneNumber.
discounts	MerchantDiscountsRequest		Discount codes submitted by the shopper. Validate and return applied or rejected results.
affiliateAttribution	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		Units requested. Must be 1 or more.
lineItems[].id	String		Product or SKU identifier. Echo back in MerchantLineItem.id.

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.

Possible HTTP status codes

(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. Adyen distinguishes them by whether the sessionId already exists in your system.

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. On update requests, fields that have not changed can be omitted.

Path parameter:

Request headers:

Body parameters:

Your server response

The response schema is identical to Create session. Always return the fully recalculated state — never return only the changed fields.

Possible HTTP status codes

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

Request headers:

Body parameters:

Your server response

No response body is expected. Return the appropriate HTTP status code.

Possible HTTP status codes

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

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:

Request headers:

Body parameters:

Parameter	Type	Required	Description
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[].totalAmount	Object		Final line total (subtotal + tax) in minor currency units.
billingAddress	MerchantAddress		The shopper's billing address at checkout completion.
fulfillmentOptions	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		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[]		Merchant policy links from the session.
reference	String		Session reference.

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

Possible HTTP status codes

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.

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:

Request headers:

Body parameters:

Parameter	Type	Required	Description
lineItems	Object[]		Final authorized 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.
billingAddress	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		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[]		Merchant policy links from the session.
reference	String		Session reference.

Your server response

No response body is expected. Return the appropriate HTTP status code.

Possible HTTP status codes

(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 one. Adyen sends the raw payment token, and your server executes payment authorization directly with a 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:

Request headers:

Body parameters:

Parameter	Type	Required	Description
paymentData	Object		The payment token. Pass paymentData.token as paymentMethod.storedPaymentMethodId in your POST /payments request.
paymentData.provider	String		Payment provider. Always adyen for this integration.
paymentData.token	String		The ACP token from Adyen. Pass as paymentMethod.storedPaymentMethodId in your 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 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		The shopper's billing address.
shopper	MerchantShopper		Shopper contact details.
marketingConsents	MerchantMarketingConsent[]		The shopper's marketing opt-in or opt-out choices.
affiliateAttribution	MerchantAffiliateAttribution		Attribution data for tracking.
reference	String		Session reference.

1. Get the information that you need to make a payment request to Adyen.

Your server response

The success HTTP 200 response includes the following:

Possible HTTP status codes

Make the payment request to Adyen

2. Make a 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:

Request headers:

Request body:

Parameter	Type	Required	Description
eventCode	String		The type of event. For example, ORDER_SHIPPED.
payload	Object		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.

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 and update session endpoints return 200 with the following:
     • lineItems
     • fulfillmentOptions
     • totals
   • Your server's commit-session endpoint validates the X-Merchant-Account header in the request.
   • Your server's finalize session endpoint:
     • Validadtes the X-Merchant-Account header in the request.
     • Returns 204 No Content (no response body).
   • Your server's 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 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 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):

Advanced flow (ACP):

Standard flow (UCP):

Schema reference

The following shows the objects used in the request and response bodies.

MerchantItemRequest

MerchantAddress

MerchantShopper

MerchantFulfillment

MerchantDiscountsRequest

MerchantDiscountsResponse

MerchantAppliedDiscount

Parameter	Type	Required	Description
id	String		Unique identifier for this applied discount.
amount	Integer (int64)		Total discount amount in minor currency units.
coupon	MerchantCoupon		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[]		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)		Discount amount allocated to this line item in minor currency units.
path	String		JSON pointer to the line item, for example, /lineItems/0.

MerchantRejectedDiscount

Parameter	Type	Required	Description
code	String		The discount code that was rejected.
reason	MerchantDiscountErrorCode		Machine-readable rejection reason.
message	String		Human-readable explanation. Surface this to the shopper.

MerchantDiscountErrorCode

MerchantCoupon

Parameter	Type	Required	Description
id	String		Unique coupon identifier.
name	String		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).
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		Marketing channel, for example, email, sms, push.
optedIn	Boolean		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		Channel identifier, for example, email, sms.
displayText	String		Localized consent prompt to show to the shopper.
privacyPolicyUrl	String		URL to your privacy policy for this channel.
isSubscribed	Boolean		Pre-populated subscription state for returning shoppers.

MerchantAffiliateAttribution

Parameter	Type	Required	Description
provider	String		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