UCP Checkout Flow

This page walks through how a purchase works through UCP — from the moment Google initiates a checkout to the moment the order is placed on the merchant’s platform.

​​ Session model

UCP uses a three-step checkout session lifecycle. Each step maps directly to Firmly’s existing cart and checkout APIs:

1. CreateCheckoutSession — Google sends the product and user context. Firmly initializes a cart on the merchant’s platform and returns session state.
2. UpdateCheckoutSession — Google sends shipping address, shipping method, or promo changes. Firmly updates the cart and returns new totals and available options.
3. CompleteCheckoutSession — Google sends payment authorization. Firmly tokenizes the payment, places the order on the merchant’s platform, and returns confirmation.

The user never leaves Google’s surface during this flow. Google owns the UI; Firmly owns the commerce backend.

​​ Step 1 — Create session

Google calls POST /checkout-sessions with line items and buyer context. Firmly:

1. Generates a device_id via crypto.randomUUID() (this becomes the session ID)
2. Calls POST /api/v2/domains/{domain}/cart/line-items?flush_cart=false to create the cart
3. Stores the session mapping in the session store
4. Returns the UCP-formatted session response

The session starts in incomplete status — shipping address, shipping method, and buyer email are still missing.

Line item limitation: cart contents are fixed at session creation. UCP does not allow adding, removing, or changing item quantities via the update endpoint. The user finalizes product selection on the Google AI surface before the checkout session begins.

​​ Step 2 — Update session

Google calls PUT /checkout-sessions/{id} as the user fills in checkout details. The wrapper inspects which fields changed and routes to the appropriate Firmly APIs:

Shipping info buffering — Google may send partial address updates as the user types. The wrapper buffers these in pending_shipping_info and only calls the shipping-info API when the address is complete and different from submitted_shipping_info. This avoids unnecessary backend calls during partial entry.

​​ Step 3 — Complete order

Google calls POST /checkout-sessions/{id}/complete when the user confirms. Firmly:

1. Retrieves the session from the session store
2. Applies the stored buyer info and payment data
3. Calls POST /api/v1/domains/{domain}/cart/complete-order
4. Returns the UCP-formatted order confirmation

The session transitions to completed — a terminal state.

​​ Session lifecycle

Sessions progress through these states as the checkout advances:

The session can move back from ready_for_complete to incomplete if a required field is removed (for example, the user clears the shipping address). Both incomplete and ready_for_complete can be canceled at any time.

​​ Discount support

Discount codes are handled through the checkout session’s update step (and can also be supplied at creation). Firmly maps UCP discounts.codes to the merchant’s promo-code endpoints:

discounts.codes uses replacement semantics: the submitted array replaces the currently applied set, and an empty array clears all codes. Codes are matched case-insensitively and de-duplicated; a strict superset of the current set is applied additively, and any other change is performed as a clear-and-re-add.

A rejected code does not fail the update — Firmly returns the updated cart with a recoverable warning in messages[]. Rejection codes include discount_code_invalid, discount_code_user_ineligible, discount_code_combination_disallowed, and discount_service_unavailable.

​​ External references

​​ Related

• UCP overview — what UCP is and why Firmly implements it
• UCP implementation — service architecture, API mapping
• UCP security — how requests are authenticated and protected