Configuration
UBM needs little configuration. The pricing engine has a default, so a new business unit works without any setting; tender configurations matter once a basket carries payment.
Price calculation engine — 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.
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: the business unit must have a country in
Business Unit Management, so UBM can reach the right per-country Checkout Engine instance. UBM takes it
from the business-unit events, or asks Business Unit Management directly — 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 is deleted or closed in Business Unit Management |
400 Bad Request saying a business unit has no country | The business unit has no country in Business Unit Management. Set it there; UBM picks it up on the next call |
Calls fail for a business unit on CHECKOUT although it exists and has a country | No Checkout Engine is provisioned for the tenant in that country |
409 Conflict on a basket write | Another request changed the same basket at the same moment. Re-read the basket and retry; serialise writes per basket to avoid it |
409 Conflict on POST …/checkout | Another request changed the basket before the customer order was created. This request created no order. Re-read the basket: if it is COMPLETED, a concurrent checkout created the order and its customerOrderId is on the basket; otherwise check out again |
| Deleting a basket returns cannot be deleted | The basket is COMPLETED. It cannot be deleted, and is removed automatically 18 months after its last change |
| 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 | On PROMOTION: the line was sent without a price, so the catalogue's was used. Send the price you displayed. On CHECKOUT the Checkout Engine prices from its own catalogue — see How pricing works |
A PROMOTION line has no item identifier | Expected when neither you nor the catalogue supplied one. That engine matches on item id and does not need it |
| 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 paid less than its total | Expected for a collection, and for a basket with no fulfillments. Tenders are optional; what is refused is over-payment and a part-paid delivery — 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; if it is missing from the calculated result's coupons, the engine did not accept it |
| Every modifying call returns Cannot modify a completed basket, or says the basket is COMPLETED or does not exist | The basket is COMPLETED. Create a new basket |