Checkout Integration Reference - Alexa+ Developer Docs

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.

Operation	Method	Path	Required?	Notes
Create	POST	`/checkout-sessions`	Required	Body requires `line_items`
Get	GET	`/checkout-sessions/{id}`	Required	Read-only; returns full current state. Required for crash recovery — Alexa+ re-fetches state after network failures
Update	PUT	`/checkout-sessions/{id}`	Required	Full-resource replace — caller resends the full object
Complete	POST	`/checkout-sessions/{id}/complete`	Required	Payment credential arrives here
Cancel	POST	`/checkout-sessions/{id}/cancel`	Optional	Transitions session state only — not an order cancellation. TTL expiration handles cleanup if you don’t hold inventory or pre-auth funds at session creation

Request and response headers

Request headers

Alexa+ sends the following headers on every call:

Header	Always?	Purpose
`UCP-Agent`	Yes	Alexa+ profile URI
`Idempotency-Key`	On state-changing calls	Store 24h minimum; replay cached result on duplicates; return `409` if same key arrives with a different body
`Request-Id`	Yes	Include in logs — required for support escalations
`Authorization: Bearer`	Yes	OAuth token (for linked-user or guest checkout). Validate and return `401` on failure
`Content-Type: application/json`	Yes	All request bodies are JSON

Response headers

Header	Required	Notes
`Content-Type: application/json`	Required	All response bodies are JSON
`Cache-Control: no-store`	Required	Checkout state must never be cached
`Request-Id` (echoed from request)	Recommended	For log correlation and support escalations

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

Field	Required	Notes
`line_items[]`	Yes	Each entry: `item.id` + `quantity`. Alexa+ may only send `item.id` as a hint — your backend is the authoritative source for title and price. You must return `title` and `price` in all responses.
`buyer`	Optional	`first_name`, `last_name`, `email`, `phone_number` — sent when known
`context`	Optional	Provisional hints: `address_country`, `address_region`, `postal_code`, `language` (BCP 47), `currency`, `intent`, `eligibility[]`
`fulfillment`	Optional	Delivery address when known upfront
`attribution`	Optional	Campaign/click IDs

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

Field	Required in responses	Notes
`id`, `status`, `currency`	Yes	`currency` is ISO 4217
`line_items[]`	Yes	Each with `item` {`id`, `title`, `price`}, `quantity`, per-line `totals`
`totals[]`	Yes	At minimum one `subtotal` and one `total`; amounts in minor units; discounts are negative. `display_text` is optional — omit for well-known types (`subtotal`, `tax`, `shipping`, `total`); provide it for custom types to ensure correct label rendering.
`links[]`	Yes	At minimum a `refund_policy` link; `terms_of_service` is common practice and expected by most buyers. Always provide a `title` — it’s displayed on the Alexa+ payment checkout screen.
`ucp`	Yes	Envelope: `version`, `status`, `capabilities`, `payment_handlers`
`buyer`, `fulfillment`, `payment`, `messages`, `continue_url`, `expires_at`, `order`	As applicable	`order` {`id`, `permalink_url`} only after completion

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:

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

You return	Alexa+ does
`incomplete` + messages	Fixes inputs, calls Update
`ready_for_complete`	Calls Complete
`completed` + order	Confirms to the buyer

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"
    }]
  }]
}

Field	Description
`methods[].id`	Unique identifier for this fulfillment method
`methods[].type`	Fulfillment type (e.g., `shipping`)
`methods[].selected_destination_id`	References the chosen destination by `id`
`methods[].line_item_ids`	Which line items this method applies to
`methods[].destinations[]`	Array of address objects with standard address fields

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:

Priority	Severity	Action
1	`recoverable`	Resolve via `PUT /checkout-sessions/{id}` — update the field indicated by `path` and retry
2	`requires_buyer_input`	Cannot be resolved via API. Initiate handoff via `continue_url`
3	`requires_buyer_review`	Buyer authorization needed. Initiate handoff via `continue_url`
4	`unrecoverable`	Session can’t proceed. Retry with new resource or inputs

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.

Presentation	Display contract	Proximity to path	Dismissible	Image (`image_url`)	Link (`url`)
`notice` (default)	MUST display content	MAY	MAY dismiss	MAY render	MAY render
`disclosure`	MUST display content	MUST (near path element)	MUST NOT dismiss	MUST render	SHOULD render

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

Code	Severity	Description
`out_of_stock`	`recoverable` or `unrecoverable`	Item/variant unavailable
`item_unavailable`	`unrecoverable`	Item can’t be purchased (e.g., delisted)
`address_undeliverable`	`recoverable`	Cannot deliver to the provided address
`payment_failed`	`recoverable` or `unrecoverable`	Payment processing failed
`eligibility_invalid`	`recoverable`	Eligibility claim could not be verified at completion

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:

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

Field	Required	Notes
`ucp`	Yes	Top-level wrapper key. All profile fields are nested inside this object.
`ucp.version`	Yes	UCP spec version — use `2026-04-08`
`ucp.capabilities`	Yes	Must include `dev.ucp.shopping.checkout` with `version`, `spec`, and `schema` fields.
`ucp.services`	Yes	Declares the REST transport and sets the base URL for all five endpoints. Alexa+ constructs all endpoint URLs relative to the declared `endpoint`.
`ucp.payment_handlers`	Yes	One entry per supported handler; declarations must match what the session returns in `ucp.payment_handlers`

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

Resource	URL
UCP Checkout REST spec	https://ucp.dev/specification/checkout-rest/
UCP Checkout object spec	https://ucp.dev/specification/checkout/
UCP Discovery spec	https://ucp.dev/specification/discovery/
UCP Signature spec	https://ucp.dev/latest/specification/signatures/
Checkout session schema	https://ucp.dev/2026-04-08/schemas/shopping/checkout.json
card_payment_instrument schema	https://ucp.dev/2026-04-08/schemas/shopping/types/card_payment_instrument.json
payment_instrument schema	https://ucp.dev/2026-04-08/schemas/shopping/types/payment_instrument.json
payment_credential schema	https://ucp.dev/2026-04-08/schemas/shopping/types/payment_credential.json
UCP Fulfillment reference	https://ucp.dev/2026-04-08/specification/reference/#fulfillment

​Operations

​Request and response headers

​Request headers

​Response headers

​Create

​Create request fields

​Create request example

​Create response example (201)

​Get

​Update

​Update request example

​Update response example (200)

​Complete

​Complete request example

​Complete response — success (200)

​Complete response — payment declined (200)

​Cancel

​Object definitions

​Checkout object

​Required fields

​Session lifecycle

​Status transitions

​Status and Alexa+ behavior

​Fulfillment object

​Errors and messages

​Message structure

​Error severity levels

​Warning presentation types

​Standard error codes

​Payment methods

​Network Token (com.amazon.payments.network_token)

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

​Discovery profile

​Full profile example

​Profile fields

​Handler registration rules

​Handler versioning

​UCP reference links

​Related topics