Skip to main content

Data sources

UBM holds only the basket. Everything else it needs, it reads at request time from other services. This page lists every ingress and egress, so you can tell which system to look at when a value looks wrong.

Your channel sends requests to Unified Basket Manager and gets the priced basket back in the response. UBM reads item data from product data and each store's country from the business units, prices the basket with the Checkout Engine, which returns price and tax and is the default, or the Promotion Engine, which returns price only, and at checkout creates a customer order.

Product master data​

UBM reads item data per request with one product-and-price (PnP) query, the complete item query. It returns an item's name, sales unit of measurement, category, price specifications and identifiers: the enrichment described in How pricing works. Nothing is imported in advance, so a catalogue change is visible to the next recalculation.

UBM looks an item up only when a line is missing something it needs:

WhenUBM looks the item up if the line has no…
A line is added or replaced on a CHECKOUT business unititem identifier
A line is priced on a PROMOTION business unitprice, name, unit of measurement, category or tax group
Checkout, on either enginecategory or tax group

So a storefront that sends what it already knows makes few catalogue calls.

⚠ The item identifier is a Checkout Engine concern. The Checkout Engine matches items the way a till does — on the identifier that would be scanned, a GTIN or PLU — so a basket priced by it needs one per line. The Promotion Engine matches on the item id instead and does not need an identifier at all. So a business unit on PROMOTION need not supply GTIN/PLU.

The Checkout Engine matches items the way a till does, on the code that would be scanned, a GTIN or PLU, so every line it prices needs an identifier. The Promotion Engine matches on the item id and needs no identifier.

⚠ A product-master failure fails the request. UBM does not price a basket from partial catalogue data — if item data cannot be fetched, the call returns an error rather than falling back to whatever you supplied. This is deliberate: a silently mispriced basket is worse than a failed request.

When product data cannot be reached, the request fails and the basket is left as it was. Unified Basket Manager never prices a basket from part of the item data.

Business-unit country codes​

UBM keeps its own copy of the country code of each business unit, kept up to date from the business-unit events published by Business Unit Management. When its copy has no country for a business unit, it asks Business Unit Management directly. It needs the country for one purpose: resolving which per-country Checkout Engine instance to call.

Consequences worth knowing:

  • A newly created business unit can be priced on CHECKOUT straight away, because UBM asks for its country when it has not received it yet. Business units on PROMOTION do not need a country.
  • A business unit that is deleted or closed gets 404 Not Found on CHECKOUT.
  • A business unit with no country in Business Unit Management cannot be priced on CHECKOUT; the call returns 400 Bad Request naming the business unit.
  • A country change on an existing business unit takes effect shortly after the corresponding event arrives.

The calculation engines​

Covered in How pricing works. Whichever applies is called synchronously, inside the request:

  • Checkout Engine — HTTP, one instance per tenant and country, stateful, returns price and tax
  • Promotion Engine — gRPC, a single shared multi-tenant instance, stateless, returns 🛑 price only, no tax

Customer Order​

At checkout UBM calls the Customer Order service to create the order, then marks the basket completed. UBM does not own the order afterwards, and does not track its fulfillment or payment lifecycle — see Checkout.

Identity and access​

UBM calls the IAM service to resolve permissions, and the business-unit service for business unit details. Callers authenticate as they do elsewhere on the platform; every endpoint is business-unit-addressed, so the caller's access to that business unit governs the call.

What UBM stores itself​

Only basket state: the input basket and its sub-resources, the calculated result, tender configurations and tender authorization data, and the per-business-unit engine selection. Baskets are working state, not a system of record — once a basket is checked out, the durable record is the customer order.