# UCP Checkout for Magento 2  -  module reference

> Let UCP agents build a Magento 2 checkout over REST: items, buyer, coupon, live shipping rates. The buyer pays on your own checkout.

Source: https://angeo.dev/docs/modules/ucp-checkout/
Updated: 2026-10-17

Module reference

# UCP Checkout for Magento 2  -  module reference

Covers `angeo/module-ucp-checkout` 1.1.0 - Checked 16 October 2026 - MIT licensed

**UCP Checkout** adds the UCP **checkout** capability (`dev.ucp.shopping.checkout`, spec 2026-08-25) with the **discount** and **fulfillment** extensions, plus the **order** capability since 1.1.0.

An agent that speaks UCP  -  the protocol behind Google AI Mode and Gemini checkout  -  can create a checkout session over REST, add items, set the buyer, a coupon code and a shipping address, pick one of your live shipping rates and see live totals. When the buyer is ready, the agent sends them to `continue_url`. Their cart opens on your store with the address and shipping method already set, and they pay as usual.

**No card data, no payment handler, no PCI scope.**

Package`angeo/module-ucp-checkout`Latest version1.1.0 (released 2026-10-14)Magento2.4.6+PHP8.1 - 8.5Payment through the agentNo  -  handoff to your checkout via continue_urlLicenseMIT, freeLinks[GitHub](https://github.com/angeo-dev/module-ucp-checkout) - [Packagist](https://packagist.org/packages/angeo/module-ucp-checkout) - [Changelog](https://github.com/angeo-dev/module-ucp-checkout/blob/main/CHANGELOG.md) - [Module page](https://angeo.dev/modules/ucp-checkout/)

**On this page**

1. Operations
2. Requirements
3. Installation
4. Setting it up
5. Try it
6. Configuration reference
7. Cron and stored data
8. Conformance
9. Not included yet
10. FAQ
11. Related

## Operations

| Operation | Endpoint | What happens |

| Create Checkout | `POST {endpoint}/checkout-sessions` | New guest quote with the items -> `201` |
| Get Checkout | `GET {endpoint}/checkout-sessions/{id}` | Items, totals, status |
| Update Checkout | `PUT {endpoint}/checkout-sessions/{id}` | **Full replacement**: lines, buyer, discount code, shipping |
| Complete Checkout | `POST {endpoint}/checkout-sessions/{id}/complete` | `requires_escalation` + `continue_url`  -  never charges |
| Cancel Checkout | `POST {endpoint}/checkout-sessions/{id}/cancel` | Session and quote closed |
| Get Order | `GET {endpoint}/orders/{order number}` | Status, shipments, refunds |
| continue_url | `GET /ucp/checkout/continue/{token}` | Loads the cart in the buyer's browser, then opens `/checkout` |

`{endpoint}` is `https://your-store/ucp/v1` by default.

### Session status

- `incomplete`  -  something the agent can fix: no email, an unknown item, not enough stock. Messages say what and where (`path`).
- `requires_escalation`  -  everything the API can collect is there. The rest happens on your checkout through `continue_url`.
- `completed`  -  the buyer placed the order. `order.id` and `order.permalink_url` are filled in.
- `canceled`  -  cancelled by the agent, or expired (default after 6 hours).

### Shipping

One `shipping` method, one destination and one group. The agent writes the address into `fulfillment.methods[0].destinations[0]`. The response lists your live Magento rates for that address as `groups[0].options`, cheapest first. The agent picks one with `selected_option_id`. Countries outside your allowed countries and unknown options come back as fixable errors with a `path`. An update without `fulfillment` clears the address and the rate. Pickup is not offered.

### Orders and webhooks (1.1.0)

After the buyer orders, the agent can read the order at `GET {endpoint}/orders/{order number}`: line status, shipments with tracking, refunds, cancellation and totals. Only the platform whose `UCP-Agent` profile created the checkout gets the order. Others get `404`. Set **Request Security -> Inbound Signature Verification** to *required* in UCP Profile, so the profile is proven by a signature.

If the platform's profile declares a `webhook_url` for the order capability, the store POSTs the order to it on create, shipment, refund and cancel. Each call is signed (RFC 9421 + `Content-Digest`) with your store key and carries `Webhook-Id` and `Webhook-Timestamp`. A cron job sends every minute and retries after 1 min, 5 min, 30 min, 2 h and 12 h.

Webhook signing needs the private key in `app/etc/env.php`, as `angeo:ucp:keys:generate` prints it. The key id must also be published in the profile.

```
'ucp' => ['signing_keys' => ['<kid>' => '-----BEGIN PRIVATE KEY-----...']],
```

### Ids, idempotency and versions

- **Item ids:** `gid://magento/ProductVariant/{id}` (as returned by [UCP Catalog](https://angeo.dev/docs/modules/ucp-catalog/)), `gid://magento/Product/{id}` for simple products, or a plain SKU. Configurable children are added through their parent.
- **Idempotency-Key** on create, update, complete and cancel: the same key and body replays the stored answer. The same key with a different body gives `409`. Keys are kept 24 hours.
- **Version negotiation** through `UCP-Agent: profile="..."; version="..."`. Versions the store serves are accepted. Others get `422`.

## Requirements

| Magento | 2.4.6+ (Open Source, Mage-OS or Adobe Commerce)  -  `magento/framework >=103.0.6 <104` |
| PHP | 8.1 - 8.5  -  `~8.1.0||~8.2.0||~8.3.0||~8.4.0||~8.5.0` |
| Other angeo modules | [angeo/module-ucp](https://angeo.dev/docs/modules/ucp/) `^2.2` |
| PHP extensions | `json` |

## Installation

```
composer require angeo/module-ucp-checkout
bin/magento module:enable Angeo_UcpCheckout
bin/magento setup:upgrade
bin/magento setup:di:compile                # production mode only
bin/magento cache:flush
```

## Setting it up

In **Stores -> Configuration -> Angeo -> UCP (Universal Commerce Protocol)**:

1. **Declared Root Capabilities -> Checkout** = *Yes*. Optional: **Order**, and **Declared Extensions -> Discount** and **Fulfillment**.
2. **Transport -> REST Endpoint URL**: leave empty (`{baseUrl}/ucp/v1`), or enter your own HTTPS URL.
3. **Checkout Sessions**: your terms, privacy and refund links (sent in every checkout), the session lifetime and the limits.
4. Check the profile:

```
bin/magento angeo:ucp:validate
curl -s https://your-store/.well-known/ucp | jq '.ucp.capabilities | keys'
```

Exclude `/ucp/` from full-page cache (Varnish, LiteSpeed, Cloudflare). The responses send `Cache-Control: no-store`.

## Try it

```
curl -s -X POST https://your-store/ucp/v1/checkout-sessions \
  -H 'Content-Type: application/json' \
  -H 'UCP-Agent: profile="https://agent.example/profile"' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"line_items":[{"item":{"id":"24-MB02"},"quantity":1}],
       "buyer":{"email":"jane@example.com"}}' | jq '{id, status, totals, continue_url}'
```

## Configuration reference

All settings are under **Stores -> Configuration -> Angeo -> UCP (Universal Commerce Protocol)**. The table shows each field, its config path (for `bin/magento config:set`) and its default value.

Checkout Sessions (angeo/module-ucp-checkout) (8)

| Setting | Config path | Default |

| Session Lifetime (hours) | `angeo_ucp/checkout/session_ttl_hours` | `6` |
| Max Line Items per Session | `angeo_ucp/checkout/max_line_items` | `50` |
| Max Quantity per Line | `angeo_ucp/checkout/max_quantity` | `1000` |
| Terms of Service URL | `angeo_ucp/checkout/terms_url` |  -  |
| Privacy Policy URL | `angeo_ucp/checkout/privacy_url` |  -  |
| Refund / Returns Policy URL | `angeo_ucp/checkout/refund_url` |  -  |
| Handoff Page Path | `angeo_ucp/checkout/handoff_path` | `checkout` |
| Keep Expired Sessions (days) | `angeo_ucp/checkout/retention_days` | `30` |

## Cron and stored data

| Job | Cron group | Schedule |

| `angeo_ucp_checkout_webhooks` | `default` | `* * * * *` |
| `angeo_ucp_checkout_cleanup` | `default` | `17 3 * * *` |

| Table | What it holds | Columns |

| `angeo_ucp_checkout_session` | Angeo UCP checkout sessions | `entity_id, session_id, quote_id, store_id, status, agent_profile, continue_token, item_refs, pending_messages, snapshot, order_id, order_increment_id, order_url, destination_id, expires_at, created_at, updated_at` |
| `angeo_ucp_order_webhook` | Angeo UCP order webhook queue | `entity_id, event_id, order_id, session_id, event, status, attempts, last_status, last_error, next_attempt_at, created_at` |
| `angeo_ucp_checkout_idempotency` | Angeo UCP checkout idempotency keys | `entity_id, operation, idempotency_key, session_id, request_hash, http_status, response_body, created_at` |

## Conformance

The official [UCP conformance suite](https://github.com/Universal-Commerce-Protocol/conformance) also tests completing a checkout with payment. This module does not do that on purpose, so a full run will not pass every test. Discovery, version negotiation, the create/get/update/cancel lifecycle, idempotency and shipping options are the parts it is built to pass.

## Not included yet

- Payment through the agent (payment handlers, AP2, card credentials).
- Pickup, or several destinations or packages per checkout.
- Checkouts for signed-in customers over the API (identity linking).

## FAQ

### Does the agent take payment?

No. Complete Checkout returns requires_escalation and a continue_url. The buyer opens it, lands on your checkout with the cart ready, and pays there.

### Which shipping rates does the agent see?

Your live Magento rates for the address the agent sends, cheapest first. The agent picks one, and it shows up in the totals.

### Can another platform read my orders?

No. Only the platform whose UCP-Agent profile created the checkout can read the order. Use the required signature mode so that profile is proven.

### How do retries work?

Send an Idempotency-Key. The same key with the same body returns the stored answer. The same key with a different body gives 409.

### Can agents use MCP instead of REST?

Yes. Install UCP Checkout over MCP. It adds the same five operations as MCP tools and shares sessions with REST.

## Related

- [UCP Profile](https://angeo.dev/docs/modules/ucp/)  -  a signed /.well-known/ucp profile for UCP agents
- [UCP Catalog](https://angeo.dev/docs/modules/ucp-catalog/)  -  catalog.search and catalog.lookup endpoints behind the UCP profile
- [UCP Checkout over MCP](https://angeo.dev/docs/modules/ucp-checkout-mcp/)  -  the same UCP checkout as five MCP tools
- [AI Agent Activity](https://angeo.dev/docs/modules/agent-activity/)  -  report on AI agent calls, crawler visits, fake bots and agent-built orders
- [MCP Checkout](https://angeo.dev/docs/modules/mcp-checkout/)  -  guest cart and checkout tools for AI agents, with server-side limits
- [UCP for Magento 2  -  complete guide](https://angeo.dev/magento-ucp/)
- [UCP checkout  -  definition](https://angeo.dev/ucp-checkout-definition/)
- [All module reference pages](https://angeo.dev/docs/modules/) - [Compatibility matrix](https://angeo.dev/docs/compatibility/)

This page was written from the `README.md`, `composer.json` and `etc/*.xml` files of [tag 1.1.0](https://github.com/angeo-dev/module-ucp-checkout/tree/1.1.0), read on 16 October 2026. Settings, commands and defaults come straight from that code. If a newer release is out, the README on GitHub wins.