Implement the Checkout Endpoints

This guide describes how to implement your checkout endpoints for your Alexa+ add-on. To power transactions in Alexa+, you implement a set of REST-based checkout endpoints that Alexa+ calls to create, update, and complete purchase sessions. The session schemas and field contracts follow industry-standard patterns defined by the Universal Commerce Protocol (UCP). This enables future interoperability with other AI agent services. For the full endpoint reference, see Checkout Integration Reference.

Key concepts

Before you begin implementation, understand these three core concepts that control the checkout integration.

The checkout session

A checkout session is a stateful object that tracks a purchase from creation to completion. Alexa+ creates a session when the customer initiates checkout, updates it as details are collected (shipping address, fulfillment method), and completes it when payment is processed. Your backend is responsible for all business logic — pricing, tax, inventory, and fulfillment — and returns the full session state on every response. For the session schema and status lifecycle, see Checkout object.

Payment handlers

Payment handlers define how payment credentials are exchanged between Alexa+ and your backend. You declare which handlers you support, and Alexa+ negotiates the best mutual handler for each session. Alexa+ never transmits a raw Primary Account Number (PAN) — all card data is tokenized or referenced by ID. Two handlers are available:

Network Token (com.amazon.payments.network_token) — The customer pays with a card from their Amazon wallet. Alexa+ delivers an encrypted token that you decrypt and submit to your Payment Service Provider (PSP). Requires Amazon Pay merchant onboarding.
Stored Payment Method (com.amazon.payments.stored_payment_method) — The customer pays with a card already saved in their account with you. You return the list of saved cards; Alexa+ returns the chosen card’s ID at completion. Requires account linking.

You declare your supported handlers in the ucp.payment_handlers block of every checkout session response. Alexa+ reads this block to determine which credential type to acquire before calling Complete. For credential shapes and processing steps, see Payment methods.

The discovery profile (`.well-known/ucp`)

The discovery profile is a JSON document you host at https://your-domain.com/.well-known/ucp. It tells Alexa+ where your checkout endpoints are, which capabilities you support, and which payment handlers are available. Alexa+ fetches this profile during onboarding and uses it to route checkout requests to your service. For the full profile schema, see Discovery profile.

High-level steps to implement

The following table summarizes the steps to implement checkout.

Step	What to build	Reference
1	Choose your integration model. This depends on how you built your add-on, with the MCP Toolkit or Category SDK.	Integrate with MCP Toolkit or Category SDK
2	Set up OAuth 2.0 bearer token validation.	Authentication
3	Implement the required endpoints and understand the session lifecycle: Create — respond with totals, payment handlers, and messages Get — return current session state for crash recovery Update — full-resource replace; calculate shipping and tax Complete — receive and process the payment credential Cancel (optional) — transition session state	Checkout Integration Reference:
4	Implement error handling — severity, codes, warnings, disclosures.	Errors and messages
5	Choose and implement your payment handler(s) — Network Token, Stored Payment Method, or both.	Payment methods
6	Publish your `.well-known/ucp` discovery profile.	Discovery profile
7	Add fulfillment support (if applicable).	Fulfillment
8	Review security requirements — idempotency and TLS.	Security and trust

Integrate with MCP Toolkit or Category SDK

The checkout endpoints are the same regardless of whether you use MCP Toolkit or Category SDK integration to build your add-on. Only the discovery mechanism and checkout trigger differ.

MCP Toolkit integration

Your existing MCP App experience is integrated with Alexa+. You fully control the customer experience. Alexa orchestrates the checkout flow by making MCP tool calls. The checkout step requires a handoff to Alexa+ for order confirmation, payment instrument selection, and order placement.

Discovery phase — via MCP tool calls
Checkout screen rendering — your MCP App manages the UX
Payment phase — Alexa+ manages the CX and calls UCP REST endpoints directly

If your MCP App includes touch-based purchase actions (such as a “Book Now” or “Pay” button), wire these actions to trigger the checkout flow. See How checkout is triggered for details. Sequence diagram showing interactions for payments with an MCP add-on

Sequence diagram showing interactions for payments with an MCP add-on

Category SDK integration

Alexa+ renders curated experiences where the customer experience is fully controlled by Alexa+. The Category SDK supports two types of add-ons, category action and category MCP. For both types, Alexa+ still provides the full customer experience.

Category action add-on—Based on the category your business falls under, you implement specific SPI contracts defined by Alexa, which are HTTP endpoint mappings to your backend services.
Category MCP add-ons—Alexa+ invokes tools in your MCP server to interact with your backend services.

The payment flow works the same for both types of add-ons.

Discovery phase — via SPI calls implemented by your add-on or MCP tool calls for a category MCP add-on.
Checkout screen rendering — Alexa+ owns UX
Payment phase — Alexa+ manages the CX and calls UCP REST endpoints directly

Sequence diagram showing interactions for payments with a Category add-on

How checkout is triggered

The checkout flow is owned by Alexa+. Alexa+ handles voice PIN, payment instrument selection, and purchase confirmation — you don’t implement payment UX. The checkout flow can be triggered in two ways: voice or touch.

Voice

The customer speaks a purchase intent (for example, “Buy this” or “Book this hotel”). Alexa+ recognizes the payment intent from the voice input and initiates the checkout flow using prior conversation context. This works the same for all integration types — no additional implementation is needed on your part.

Touch (MCP Toolkit only)

For MCP Toolkit integrations, when the customer taps a purchase action in your MCP App (such as a “Book Now” or “Pay” button), the app must send a ui/message to signal the payment intent. Alexa+ processes it identically to a voice trigger. The ui/message contract:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "ui/message",
  "params": {
    "role": "user",
    "content": {
      "type": "text",
      "text": "Pay for this order"
    }
  }
}

What you must do:

Wire purchase-action UI elements (buttons, CTAs) in your MCP App to send ui/message via postMessage (the browser window messaging API).
Ensure the message text clearly expresses the purchase intent.
Ensure prior MCP tool results have provided sufficient product context (ID, price, policies).

What you must NOT do:

Don’t implement payment UI (no card entry, no wallet display, no PIN prompts)
Don’t use tools/call for payment actions
Don’t pass payment data in the ui/message text

After either trigger, the same checkout flow proceeds: Alexa+ creates the checkout session (POST /checkout-sessions), handles voice PIN and payment credential acquisition, and completes the session (POST /checkout-sessions/{id}/complete).

Authentication

All checkout endpoints must be secured by OAuth 2.0 using a bearer token. If your Alexa+ integration uses account linking, no additional authentication work is necessary — Alexa+ uses the Authorization Code Grant flow, and the same access token Alexa+ uses for authenticated calls to your endpoints is used for all checkout requests. The UCP Identity Linking capability (dev.ucp.common.identity_linking) isn’t used and doesn’t need to be declared in your .well-known/ucp profile. For guest checkout integrations, Alexa+ uses the Client Credentials Grant flow to obtain a bearer token. This token identifies Alexa+ as the caller but doesn’t represent a user. Stored Payment Method is unavailable for guest checkouts as there is no linked user to resolve saved cards from.

Grant	Token type	Use case	Payment handlers available
`authorization_code`	User access token (via Alexa Account Linking)	Linked-user checkout	Network Token, Stored Payment Method
`client_credentials`	Agent token (`client_id` / `client_secret` issued at onboarding)	Guest checkout	Network Token only

Your responsibilities

Validate the Bearer token on every request
Return 401 for missing, expired, or invalid tokens
Distinguish grant type to determine which handlers are available for the session

Request and response example

The following shows a minimal Create request with all required headers, followed by the matching response: Request:

POST /checkout-sessions HTTP/1.1
Host: api.partner.com
Authorization: Bearer eyJhbGciOi...
UCP-Agent: profile="https://alexa.amazon.com/.well-known/ucp"
Idempotency-Key: 7f3c9a2e-4b1d-4f0a-9c2e-000000000001
Request-Id: req-a1b2c3
Content-Type: application/json

{ "line_items": [{ "item": { "id": "sku_123" }, "quantity": 1 }] }

Response: Your server sends this response after a successful Create call.

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store
Request-Id: req-a1b2c3

{ "ucp": { ... }, "id": "chk_9001", "status": "incomplete", ... }

Echo Request-Id back in every response. Include this value when reporting an issue to Amazon — it identifies the exact request in Alexa+ logs. For full request and response examples for each endpoint, see the Checkout Integration Reference.

Idempotency

Alexa+ sends an Idempotency-Key header on all state-changing calls (Create and Complete). Complete is the critical case — a retried Complete that re-processes payment can charge the buyer twice. You must store the result keyed by Idempotency-Key for 24 hours minimum and follow these two rules:

When both the key and body match a previous request, replay the cached result.
When the key matches a previous call, but the body is different, reject the request.

Same key + same body → replay the cached result:

POST /checkout-sessions HTTP/1.1
Idempotency-Key: 7f3c9a2e-4b1d-4f0a-9c2e-000000000001

HTTP/1.1 201 Created   ← store this; return it verbatim on any retry with the same key

The same rule applies to Complete — replay the original 200 completed without re-processing the payment. Same key + different body → reject:

POST /checkout-sessions HTTP/1.1
Idempotency-Key: 7f3c9a2e-4b1d-4f0a-9c2e-000000000001
{ ... different body ... }

HTTP/1.1 409 Conflict
{ "code": "idempotency_conflict", "content": "Key was used with a different request body" }

Fulfillment

Alexa+ supports fulfillment. The fulfillment object carries the shipping destination and method. Alexa+ passes any address already in the buyer’s profile; you validate it, calculate shipping cost and tax, and return updated totals[] in the Update response. For the fulfillment object structure, see Fulfillment object in the Checkout Integration Reference. For supported fulfillment types, see the UCP Fulfillment specification.

Your responsibilities

Validate the address is deliverable — return address_undeliverable (severity: recoverable) if the address can’t be served
Calculate shipping cost and tax for the destination and return updated totals[]
Return ready_for_complete once a valid address and fulfillment method are confirmed

Security and trust

Mechanism	Status	Details
Idempotency	Required	UUID on all mutations — aligns with UCP spec
PCI scope	Existing	PSP tokens — merchant never touches raw PAN
Transport	Required	HTTPS + TLS 1.3 minimum
Message signatures	Post-launch (planned)	RFC 9421 HTTP Message Signatures. Keys published in `signing_keys[]` of each party’s `.well-known/ucp` profile.

Launch readiness checklist

Confirm each item before requesting production credentials.

Get Started

Build with the MCP Toolkit

Build with the Category SDK

Testing

Certification

Reference

Key concepts

The checkout session

Payment handlers

The discovery profile (`.well-known/ucp`)

High-level steps to implement

Integrate with MCP Toolkit or Category SDK

MCP Toolkit integration

Category SDK integration

How checkout is triggered

Voice

Touch (MCP Toolkit only)

Authentication

Your responsibilities

Request and response example

Idempotency

Fulfillment

Your responsibilities

Security and trust

Launch readiness checklist

​Key concepts

​The checkout session

​Payment handlers

​The discovery profile (.well-known/ucp)

​High-level steps to implement

​Integrate with MCP Toolkit or Category SDK

​MCP Toolkit integration

​Category SDK integration

​How checkout is triggered

​Voice

​Touch (MCP Toolkit only)

​Authentication

​Your responsibilities

​Request and response example

​Idempotency

​Fulfillment

​Your responsibilities

​Security and trust

​Launch readiness checklist

​Related topics

Key concepts

The checkout session

Payment handlers

The discovery profile (`.well-known/ucp`)

High-level steps to implement

Integrate with MCP Toolkit or Category SDK

MCP Toolkit integration

Category SDK integration

How checkout is triggered

Voice

Touch (MCP Toolkit only)

Authentication

Your responsibilities

Request and response example

Idempotency

Fulfillment

Your responsibilities

Security and trust

Launch readiness checklist

Related topics