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.

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.

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

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.

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

Launch readiness checklist

Confirm each item before requesting production credentials.

• .well-known/ucp profile published, reachable, and serving correct Content-Type
• All 4 required endpoints implemented and returning correct HTTP status codes
• Session responses include all required fields: id, status, currency, totals[], links[], ucp
• Idempotency implemented on Create and Complete — 24h key storage minimum
• Payment credential processing validated: Network Token Integration Guide provided by your Solutions Architect followed / Stored Payment Method vault ownership verified
• Account linking configured (required for Stored Payment Method)
• Errors and warnings returning correct type, code, and severity
• messages[] included in all responses (may be empty)
• Sandbox end-to-end checkout flow tested
• OAuth credentials registered with Solutions Architect
• Solutions Architect sign-off received
• Production API credentials issued

Related topics

• Checkout Integration Reference
• Payments for Alexa+

Last updated: Aug 19, 2026