Checkout Integration Reference

This document defines the REST checkout endpoints that you implement to power transactions through Alexa+. The session schemas and field contracts follow the Universal Commerce Protocol (UCP).

Alexa+ acts as an AI agent in this model: it isn't the merchant of record, doesn't own cart logic, and doesn't calculate taxes, validate inventory, or determine fulfillment options. Your backend is the authoritative source of truth for all cart state, pricing, tax, inventory, and fulfillment.

In requests, Alexa+ provides line_items (typically item.id only as a hint), buyer context fields, and fulfillment address when known. In responses, you own all business logic — pricing, tax calculation, inventory validation, fulfillment options, payment handler declaration, and messages[]. Never derive pricing or availability from Alexa+'s request values.

The session contract, schema structure, and .well-known/ucp profile format are grounded in the open UCP spec — your session logic, schema validation, and profile structure are reusable when connecting to additional AI agent services that support UCP. The payment handler declarations (com.amazon.payments.*) are Amazon-specific and would need to be updated with each service's native handler declarations. Additional capabilities such as dev.ucp.shopping.catalog and dev.ucp.shopping.orders can be declared alongside the checkout capability without modifying your existing endpoints.

Operations

You host these endpoints at a base URL declared in your .well-known/ucp profile. All endpoints use HTTPS with TLS 1.3 minimum and JSON request/response bodies.

Request and response headers

Request headers

Alexa+ sends the following headers on every call:

Response headers

Status codes: 201 for Create, 200 for all other successful operations — including business failures like payment declines (HTTP 200 + messages[]). Use 4xx/5xx only for protocol errors such as auth failures, idempotency conflicts, or malformed requests.

Create

POST /checkout-sessions

Alexa+ sends line_items and buyer context. You respond with the full checkout object — including totals, payment handler declaration, and any recoverable messages for fields still needed.

Create request fields

Create request example

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: 7f8c3e2a-1b4d-4c9f-a2b3-0e1d2f3a4b5c
Request-Id: req_abc123
Content-Type: application/json

{
  "line_items": [
    {
      "item": { "id": "sku-widget-2pk", "title": "Widget 2-Pack", "price": 14250 },
      "quantity": 2
    }
  ],
  "buyer": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com"
  },
  "context": { "language": "en-US", "address_country": "US" }
}

Create response example (201)

{
  "id": "cs_a1b2c3d4-e5f6-7890",
  "status": "incomplete",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_1",
      "item": { "id": "sku-widget-2pk", "title": "Widget 2-Pack", "price": 14250 },
      "quantity": 2,
      "totals": [
        { "type": "subtotal", "amount": 28500 },
        { "type": "total", "amount": 28500 }
      ]
    }
  ],
  "totals": [
    { "type": "subtotal", "amount": 28500 },
    { "type": "tax", "amount": 0 },
    { "type": "total", "amount": 28500 }
  ],
  "ucp": {
    "version": "2026-04-08",
    "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-04-08" }] },
    "payment_handlers": {
      "com.amazon.payments.network_token": [{
        "id": "amazon_pay_network_token",
        "version": "2026-04-08",
        "available_instruments": [{ "type": "card", "constraints": { "brands": ["visa", "mastercard"] } }]
      }]
    }
  },
  "messages": [
    {
      "type": "error",
      "code": "missing",
      "path": "$.fulfillment.methods[0].selected_destination_id",
      "content": "Delivery address is required",
      "severity": "recoverable"
    }
  ],
  "links": [
    { "type": "refund_policy", "title": "Refund Policy", "url": "https://partner.example.com/refund-policy" }
  ],
  "expires_at": "2026-06-12T05:00:00Z"
}

Status incomplete + a recoverable message tells Alexa+ to collect the missing field and call Update. The ucp.payment_handlers block declares which payment handlers this session accepts — Alexa+ uses this to negotiate the credential before calling Complete.

Get

GET /checkout-sessions/{id}

Returns the full current state of the checkout session. This is a read-only operation. Alexa+ uses Get for crash recovery — it re-fetches state after network failures to determine the correct next step.

No request body is required. The response is the full checkout object in its current state.

Update

PUT /checkout-sessions/{id}

Full-resource replace. The caller resends the complete object with updated fields. Alexa+ typically calls Update after collecting a shipping address or fulfillment selection from the buyer, or after updates to item quantities.

Update request example

PUT /checkout-sessions/cs_a1b2c3d4-e5f6-7890 HTTP/1.1
Authorization: Bearer <token>
Idempotency-Key: 9a3f1b2c-4d5e-6f70-8192-a3b4c5d6e7f8
Request-Id: req_def456
Content-Type: application/json

{
  "line_items": [
    {
      "item": { "id": "sku-widget-2pk", "title": "Widget 2-Pack", "price": 14250 },
      "quantity": 2
    }
  ],
  "buyer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com" },
  "fulfillment": {
    "methods": [{
      "id": "shipping_1",
      "type": "shipping",
      "selected_destination_id": "addr_001",
      "line_item_ids": ["li_1"],
      "destinations": [{
        "id": "addr_001",
        "street_address": "410 Terry Ave N",
        "address_locality": "Seattle",
        "address_region": "WA",
        "postal_code": "98109",
        "address_country": "US"
      }]
    }]
  },
  "context": { "language": "en-US", "address_country": "US" }
}

Update response example (200)

{
  "id": "cs_a1b2c3d4-e5f6-7890",
  "status": "ready_for_complete",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_1",
      "item": { "id": "sku-widget-2pk", "title": "Widget 2-Pack", "price": 14250 },
      "quantity": 2,
      "totals": [
        { "type": "subtotal", "amount": 28500 },
        { "type": "total", "amount": 28500 }
      ]
    }
  ],
  "totals": [
    { "type": "subtotal", "amount": 28500 },
    { "type": "shipping", "amount": 599 },
    { "type": "tax", "amount": 2394 },
    { "type": "total", "amount": 31493 }
  ],
  "ucp": {
    "version": "2026-04-08",
    "capabilities": { "dev.ucp.shopping.checkout": [{ "version": "2026-04-08" }] },
    "payment_handlers": {
      "com.amazon.payments.network_token": [{
        "id": "amazon_pay_network_token",
        "version": "2026-04-08",
        "available_instruments": [{ "type": "card", "constraints": { "brands": ["visa", "mastercard"] } }]
      }]
    }
  },
  "messages": [],
  "links": [
    { "type": "refund_policy", "title": "Refund Policy", "url": "https://partner.example.com/refund-policy" }
  ],
  "expires_at": "2026-06-12T05:00:00Z"
}

Status ready_for_complete tells Alexa+ all required fields are present — it proceeds to payment acquisition and calls Complete.

Complete

POST /checkout-sessions/{id}/complete

Alexa+ sends the payment credential based on the handler. You process payment and respond with the completed order. The request body contains only the payment instrument — no line items or totals.

The handler_id in the request reflects the customer's payment selection — amazon_pay_network_token if they paid with their Amazon wallet, partner_card_on_file if they selected a saved card from your system. Alexa+ always sends exactly one instrument.

Complete request example

POST /checkout-sessions/cs_a1b2c3d4-e5f6-7890/complete HTTP/1.1
Authorization: Bearer <token>
Idempotency-Key: b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e
Request-Id: req_ghi789
Content-Type: application/json

{
  "payment": {
    "instruments": [{
      "id": "instr_9a8b7c6d",
      "handler_id": "amazon_pay_network_token",
      "type": "card",
      "billing_address": {
        "street_address": "123 Main St",
        "address_locality": "Anytown",
        "address_region": "CA",
        "address_country": "US",
        "postal_code": "12345"
      },
      "credential": {
        "type": "encrypted_network_token",
        "encrypted_token": "eyJhbGci...",
        "encrypted_cryptogram": "eyJhbGci...",
        "eci": "05",
        "expiry_month": "09",
        "expiry_year": "2028"
      },
      "display": {
        "brand": "visa",
        "last_digits": "4242"
      }
    }]
  }
}

Complete response — success (200)

{
  "id": "cs_a1b2c3d4-e5f6-7890",
  "status": "completed",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_1",
      "item": { "id": "sku-widget-2pk", "title": "Widget 2-Pack", "price": 14250 },
      "quantity": 2,
      "totals": [
        { "type": "subtotal", "amount": 28500 },
        { "type": "total", "amount": 28500 }
      ]
    }
  ],
  "totals": [
    { "type": "subtotal", "amount": 28500 },
    { "type": "shipping", "amount": 599 },
    { "type": "tax", "amount": 2394 },
    { "type": "total", "amount": 31493 }
  ],
  "order": {
    "id": "ord-2026-0612-001",
    "permalink_url": "https://partner.example.com/orders/ord-2026-0612-001"
  },
  "messages": [],
  "links": [
    { "type": "refund_policy", "title": "Refund Policy", "url": "https://partner.example.com/refund-policy" }
  ]
}

Complete response — payment declined (200)

On a payment decline, return HTTP 200 with status incomplete and a payment_failed message. Use descriptive messages to enable Alexa+ to suggest remedial steps to the buyer. Don't return a 4xx.

{
  "id": "cs_a1b2c3d4-e5f6-7890",
  "status": "incomplete",
  "messages": [
    {
      "type": "error",
      "code": "payment_failed",
      "content": "Payment was declined. Please try a different payment method.",
      "severity": "recoverable"
    }
  ]
}

Cancel

POST /checkout-sessions/{id}/cancel

Transitions the session to canceled state. This isn't an order cancellation — it only affects the checkout session. Sessions that aren't explicitly canceled expire based on their expires_at TTL (default 6 hours).

Cancel is optional. If you don't hold inventory or pre-auth funds at session creation, TTL expiration handles cleanup automatically.

Object definitions

Checkout object

Every Alexa+ checkout response must return the full checkout object.

Required fields

ucp.status is optional — defaults to "success" and should be omitted in normal responses. Set "status": "error" only for protocol-level failures where no session resource is created. Business errors (payment declined, out of stock, missing fields) are conveyed via messages[].

Field names and payload structure align with the UCP checkout schema. You can validate payloads against public UCP schemas at any time. For additional reference, see:

• UCP Checkout REST specification
• UCP Discovery specification
• Checkout session schema

Session lifecycle

• Sessions default to a 6-hour TTL (expires_at).
• Completed sessions are immutable.
• Non-terminal sessions are cancelable if Cancel is implemented.

Status transitions

• incomplete → ready_for_complete → completed
• canceled — reachable from any non-completed state

Status and Alexa+ behavior

Fulfillment object

The fulfillment object carries the shipping destination and method. Alexa+ includes this in Update requests when a delivery address is known. Your backend validates the address, calculates shipping cost and tax, and returns updated totals[] in the response.

"fulfillment": {
  "methods": [{
    "id": "shipping_1",
    "type": "shipping",
    "selected_destination_id": "addr_001",
    "line_item_ids": ["li_1"],
    "destinations": [{
      "id": "addr_001",
      "street_address": "410 Terry Ave N",
      "address_locality": "Seattle",
      "address_region": "WA",
      "postal_code": "98109",
      "address_country": "US"
    }]
  }]
}

For supported fulfillment types, see the UCP Fulfillment specification.

Errors and messages

All checkout session responses must include a messages[] array (may be empty). Each message carries a type, code, and severity (for errors) that determines how Alexa+ processes and displays it.

Messages are discriminated by type: error, warning, or info. The content field defaults to plain text when content_type is omitted; set content_type: "markdown" for rich text rendering.

Message structure

"messages": [
  {
    "type": "error",
    "severity": "recoverable",
    "code": "address_undeliverable",
    "content": "Cannot deliver to this address. Please update.",
    "path": "$.fulfillment.methods[0].destinations[0]"
  },
  {
    "type": "error",
    "severity": "requires_buyer_review",
    "code": "eligibility_invalid",
    "content": "Age verification required to complete this purchase."
  },
  {
    "type": "warning",
    "code": "allergens",
    "path": "$.line_items[0]",
    "content": "Contains allergens: peanuts, tree nuts",
    "presentation": "disclosure",
    "image_url": "https://partner.example.com/assets/allergen-warning.png"
  }
]

Error severity levels

When multiple messages are present, they are processed in priority order:

Alexa+ resolves all recoverable errors before escalating. Only when no recoverable errors remain does Alexa+ initiate handoff for requires_buyer_input / requires_buyer_review errors.

Warning presentation types

Warning messages use the presentation field to control rendering. Default is "notice" when omitted.

Use "presentation": "disclosure" for regulatory or legal notices (allergens, Prop 65, age restrictions, subscription terms). Disclosure messages must include content; image_url should be provided.

Disclosure example with markdown rendering:

{
  "type": "warning",
  "code": "allergens",
  "path": "$.line_items[0]",
  "content": "**Contains: tree nuts.** Produced in a facility that also processes peanuts, milk, and soy.",
  "content_type": "markdown",
  "presentation": "disclosure",
  "image_url": "https://merchant.com/allergen-tree-nuts.svg",
  "url": "https://merchant.com/allergen-info"
}

Set content_type: "markdown" for rich text rendering. When omitted, content defaults to plain text.

Standard error codes

Payment methods

Alexa+ implements two payment handlers. At least one must be included in your .well-known/ucp profile. You must also include the ucp.payment_handlers block in every checkout session response — Alexa+ reads this to negotiate the credential type before calling Complete.

• com.amazon.payments.network_token — Alexa+ delivers an encrypted DPAN and cryptogram from the buyer's Amazon wallet. You decrypt the credential and submit it to your PSP as a standard network-token transaction.
• com.amazon.payments.stored_payment_method — The buyer selects a card already saved in their account with you. Alexa+ returns the chosen card's ID at Complete. No sensitive card details are shared with Alexa+.

All payment instruments use the standard card display shape. Schema references:

• card_payment_instrument.json
• payment_instrument.json
• payment_credential.json

Network Token (com.amazon.payments.network_token)

Alexa+ charges a card from the buyer's Amazon wallet. You receive an encrypted token only you can decrypt.

Prerequisite: Requires Amazon Pay merchant onboarding. Refer to the Network Token Integration Guide provided by your Solutions Architect.

Profile declaration:

"com.amazon.payments.network_token": [{
    "id": "amazon_pay_network_token",
    "version": "2026-04-08",
    "available_instruments": [{
        "type": "card",
        "constraints": {
            "brands": ["visa", "mastercard"]
        }
    }]
}]

Create/Update response: Amazon holds the card, so omit the payment node entirely. Alexa+ reads ucp.payment_handlers to know which handlers this session accepts.

{
    "ucp": {
        "version": "2026-04-08",
        "payment_handlers": {
            "com.amazon.payments.network_token": [{
                "id": "amazon_pay_network_token",
                "version": "2026-04-08",
                "available_instruments": [{
                    "type": "card",
                    "constraints": {
                        "brands": ["visa", "mastercard"]
                    }
                }]
            }]
        }
    }
}

What arrives at Complete:

{
  "payment": {
    "instruments": [{
      "id": "instr_9a8b7c6d",
      "handler_id": "amazon_pay_network_token",
      "type": "card",
      "billing_address": {
        "street_address": "123 Main St",
        "address_locality": "Anytown",
        "address_region": "CA",
        "address_country": "US",
        "postal_code": "12345"
      },
      "credential": {
        "type": "encrypted_network_token",
        "encrypted_token": "eyJhbGci...",
        "encrypted_cryptogram": "eyJhbGci...",
        "eci": "05",
        "expiry_month": "09",
        "expiry_year": "2028"
      },
      "display": {
        "brand": "visa",
        "last_digits": "4242"
      }
    }]
  }
}

Processing steps:

• Decrypt and process the credential per the Network Token Integration Guide provided by your Solutions Architect
• Return completed + order on success, or HTTP 200 with a payment_failed message on decline

billing_address is sourced from the buyer's Amazon wallet and provided by Alexa+ at Complete. Use it for Address Verification if needed. Stored Payment Method doesn't include a billing_address — you already hold it on file.

Stored Payment Method (com.amazon.payments.stored_payment_method)

The buyer pays with a card already saved in their account on your system. You return a list of cards in response to Create; Alexa+ returns the chosen card's ID at Complete. No sensitive card details are shared with Alexa+.

Prerequisite: Requires account linking — saved methods are scoped to the linked user's OAuth token.

Profile declaration:

"com.amazon.payments.stored_payment_method": [{
  "id": "partner_card_on_file",
  "version": "2026-04-08",
  "available_instruments": [{ "type": "card" }]
}]

Create/Update response: Resolve the user from the Bearer token and return saved payment instruments from their account. Use your vault/payment-method ID as the instrument ID. Provide brand and last_digits at minimum.

{
  "payment": {
    "instruments": [
      {
        "id": "pm_visa_4242",
        "handler_id": "partner_card_on_file",
        "type": "card",
        "display": {
          "brand": "visa",
          "last_digits": "4242",
          "expiry_month": "09",
          "expiry_year": "2028"
        }
      },
      {
        "id": "pm_mc_1234",
        "handler_id": "partner_card_on_file",
        "type": "card",
        "display": {
          "brand": "mastercard",
          "last_digits": "1234",
          "expiry_month": "12",
          "expiry_year": "2027"
        }
      }
    ]
  }
}

What arrives at Complete:

{
  "payment": {
    "instruments": [{
      "id": "instr_3e4f5g6h",
      "handler_id": "partner_card_on_file",
      "type": "card",
      "credential": {
        "type": "payment_method_reference",
        "payment_method_id": "pm_visa_4242"
      }
    }]
  }
}

You must validate the following before charging:

• Validate that payment_method_id belongs to the account-linked user's payment instrument
• Validate that payment_method_id was one of the IDs returned by you in the Create response

After validation is complete, use your existing processing logic to charge the payment instrument.

Discovery profile

The /.well-known/ucp profile tells Alexa+ what your integration supports. It declares your base URL, capability, and payment handlers. Serve it at https://your-domain.com/.well-known/ucp with Content-Type: application/json.

Alexa+ fetches this profile during onboarding and periodically to detect changes. Serve with a short cache TTL (15 minutes recommended).

For Alexa+-only integrations, profile negotiation is simplified — Alexa+ fetches your profile during onboarding and uses it directly. The full UCP negotiation protocol (runtime profile comparison per call) is only needed when supporting additional UCP-compatible agents beyond Alexa+.

Full profile example

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.checkout": [{
        "version": "2026-04-08",
        "spec": "https://ucp.dev/2026-04-08/specification/checkout/",
        "schema": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
      }]
    },
    "services": {
      "dev.ucp.shopping": [{
        "version": "2026-04-08",
        "transport": "rest",
        "endpoint": "https://api.partner.example.com/ucp",
        "spec": "https://PLACEHOLDER/checkout-openapi.json"
      }]
    },
    "payment_handlers": {
      "com.amazon.payments.network_token": [{
        "id": "amazon_pay_network_token",
        "version": "2026-04-08",
        "available_instruments": [
          { "type": "card", "constraints": { "brands": ["visa", "mastercard"] } }
        ]
      }],
      "com.amazon.payments.stored_payment_method": [{
        "id": "partner_card_on_file",
        "version": "2026-04-08",
        "available_instruments": [{ "type": "card" }]
      }]
    }
  }
}

Profile fields

Handler registration rules

• Each handler entry must have a unique id within the handler namespace
• available_instruments declared here are the outer bounds — a session response may narrow constraints but must not advertise instruments not declared in the profile
• Alexa+ selects the best mutual handler per session by comparing this profile against its own

Handler versioning

The checkout contract is pinned to the declared UCP spec version (2026-04-08). Each payment handler also carries a date version declared in your profile. What you build against a pinned version keeps working — the contract never changes under you. New optional fields may be added; anything requiring code changes ships as a new dated version with side-by-side support.

UCP reference links

Related topics

• Implement the Checkout Endpoints
• Payments for Alexa+

Last updated: Aug 19, 2026