Lutecia

Search Catalog

UCP catalog.search (2026-08-25): full-text product search. Prices are in ISO 4217 minor units with explicit currency fields; product/variant ids are the ids accepted by cart and checkout. merchant_name is in metadata.merchant_name. A request must carry at least one input: a query, a filter, or an extension-defined input. When `query` is omitted, the request is a browse operation: the products matching the filters are returned in catalog order, without text-relevance

Get Product

Get the full record of one catalog product. UCP catalog.lookup get_product (2026-08-25). Prices are in ISO 4217 minor units with explicit currency fields; product/variant ids are the ids accepted by cart and checkout. `catalog` (object, catalog_lookup.json#/$defs/get_product_request): - id (str, required): product or variant universal id (e.g. "client_001-wc-42") - selected (list[{name, label}], optional): option selections used to filter variants. V1: strict

Lookup Catalog

Batch lookup of products/variants by id. UCP catalog.lookup (2026-08-25). `catalog` (object, catalog_lookup.json#/$defs/lookup_request): - ids (list[str], required): product (universal id) or variant ids - filters (object, optional): - categories (list[str]): filter by category (AND with the other filters) - price (object): {max: float} - context (object, optional): {address_country, language, currency, ...} - signals (object, optional): accepted,

Create Checkout

Start a checkout (a draft order) for what the user wants to buy. UCP dev.ucp.shopping.checkout. This does NOT charge anything and does NOT place a final purchase: it creates a draft you fill in and later confirm. Call it once the user has chosen a specific variant. `checkout` (object): - line_items (required): [{"item": {"id": <catalog product/variant id>}, "quantity": <int >= 1>}] - buyer (optional): {"email", "first_name", "last_name", "phone_number"} - fulfillm

Get Checkout

Get the current state of a checkout by its `id`. Use this to re-read a checkout's `status`, `totals`, `messages`, or `order`. `id` is the checkout id returned by create_checkout. Returns the checkout as JSON.

Update Checkout

Update an existing checkout: add buyer details, shipping address, or change items. Call this to move a draft toward `status: "ready_for_complete"`, typically after asking the user for their name, email, and shipping address. `id` (required): the checkout id from create_checkout. `checkout` (object): same shape as create_checkout (line_items, buyer, fulfillment). If you omit `line_items`, the current cart is kept; buyer/fulfillment you provide replace the previous ones.

Complete Checkout

Reserve the order and get a payment link. This does NOT take any payment. It creates the order on the store as "awaiting payment" and returns a link where the user pays for it themselves. Call this ONLY after the user has explicitly confirmed the order summary, and only when the checkout `status` is "ready_for_complete". `id` (required): the checkout id from create_checkout. `meta` (required): must include `idempotency-key` (any unique string, e.g. a UUID). Generate one

Cancel Checkout

Cancel a draft order the user no longer wants. `id` (required): the checkout id from create_checkout. `meta` (required): must include `idempotency-key` (any unique string). A completed order cannot be canceled here. Returns the checkout with `status: "canceled"`.

Get Order

Get the current state of an order placed via checkout. UCP dev.ucp.shopping.order. Use this after complete_checkout to follow the order: payment received, shipped, delivered, cancelled or refunded. `id` is the order id from the completed checkout's `order.id`. Returns the order as JSON with `line_items` (each with quantity.fulfilled and a status), `fulfillment` expectations, `totals`, and `adjustments` (refunds/cancellations). Order data is authenticated: the request mu

Create Cart

Create a cart: a pre-purchase list of items with estimated totals. UCP dev.ucp.shopping.cart. Use this while the user is still exploring (comparing items, building a list). Nothing is reserved or ordered. When the user is ready to buy, call create_checkout with `{"cart_id": <this cart id>}` to convert it. `cart` (object): {"line_items": [{"item": {"id": <catalog id>}, "quantity": <int>}], "buyer" (optional), "context" (optional, e.g. {"address_country": "FR"})}. Returns

Get Cart

Get the current state of a cart by its `id`. Returns the cart as JSON (line_items, totals). A canceled or expired cart returns a not_found error.

Update Cart

Update a cart. `cart.line_items` fully replaces the current lines (UCP contract). `id` (required): the cart id from create_cart. Buyer/context you provide replace the previous ones. Returns the updated cart as JSON.

Cancel Cart

Cancel a cart the user no longer wants. `id` (required): the cart id. `meta` (required): must include `idempotency-key` (any unique string; reuse the same one when retrying this cancellation).