Configuration
UBM has little configuration, but one setting is mandatory and its absence is the most common reason a working integration returns errors against a new business unit.
Price calculation engine — required, per business unit
Names the engine that prices a business unit's baskets. Held per (tenant, business unit).
| Values | CHECKOUT — price and tax · PROMOTION — 🛑 price only, no tax. See How pricing works |
| Default when unset | CHECKOUT |
| Scope | Per business unit, so a tenant can run both engines side by side |
| Maintained through | Customer-controlled configuration, kind ubm.default-price-calculation-engine.v1 |
Because the default is CHECKOUT, a business unit needs no configuration to work: it prices with the
in-store engine until someone deliberately moves it to PROMOTION.
🛑 Choosing PROMOTION means the basket comes back with no tax — every tax group on the calculated
result is empty. It prices promotions correctly, but it only serves a channel that does not need tax from
UBM. For a webshop expecting a tax-inclusive basket it is a blocker, so leave the default in place unless
someone has confirmed the channel can do without tax.
⚠ Treat this as part of onboarding a business unit, alongside creating it. Nothing about a business unit's existence implies UBM can serve it, and this is the single most common reason a working integration starts failing against a newly created business unit.
Tender configurations
Which means of payment a business unit accepts. Tenders offered at checkout are validated against the active configurations for that business unit:
- Checkout fails with No active tender configurations found when a business unit has none.
- A tender whose configuration is not active is refused, even if the configuration exists.
So deactivating a tender configuration takes effect at the next checkout — it does not retroactively invalidate baskets, but it will stop them completing.
Business-unit country
Not a UBM setting, but a hard prerequisite for CHECKOUT: UBM must know the business unit's country
in order to reach the right per-country Checkout Engine instance. It learns this from the business-unit
event stream — see Data sources. Business units on PROMOTION do not need it.
Symptom → what to check
| Symptom | Check |
|---|---|
404 Not Found naming a tenant and business unit | The business unit's country has not reached UBM. Confirm the business unit exists in Business Unit Management and that its event has been published |
| The basket has no tax at all | The business unit is configured PROMOTION, which returns price without tax. Switch it to CHECKOUT if the channel needs tax from UBM |
| Prices differ from the in-store till for the same items | Confirm the business unit is CHECKOUT. On PROMOTION the tax half is absent, so the totals are not comparable |
| The basket priced differently from what your storefront displayed | The line was sent without a price, so the catalogue's was used. Send the price you displayed — see How pricing works |
A PROMOTION basket carries no item identifiers | Expected. That engine matches on item id and does not use identifiers |
| Checkout fails with No active tender configurations found | The business unit has no active tender configuration |
| Checkout fails on tender allocation | More than one fulfillment with unallocated tenders. Allocate tenders to fulfillments explicitly — see Checkout |
| A basket checked out with no payment, or with a tender total that did not match | Expected. Tenders are optional, and the total is only compared when the basket has both tenders and fulfillments — see Checkout |
| Adding a fulfillment or a customer did not change the total | Expected. Only items, coupons and loyalty reprice |
| Checkout says the price is not calculated for more than 2 hours | The stored calculated result has expired. Call recalculate, re-read the total, then checkout. Expect the total to be able to change |
| A coupon is on the basket but nothing was discounted | Read the calculated result. A coupon in the input basket is a request; the calculated result shows what the engine honoured |
| Every modifying call returns Cannot modify a completed basket | The basket is COMPLETED. Create a new basket |