400 on a request that looked
correct.
It builds on The booking engine model —
read that first if you haven’t.
Price rules resolve most specific first
An offering’s (or package’s)pricing is an array of rules, each scoped to
DEFAULT, COUNTRY, STATE, or POSTAL. Given a region, the server picks
the single most specific rule that matches:
POSTAL rule beats a STATE rule for the province, which beats a
COUNTRY rule, which beats DEFAULT. A POSTAL rule is considered only
within its own country and state, and each entry in its postalCodes is a
prefix: "M5V" matches M5V 2T6. Spaces and dashes are ignored, and
case doesn’t matter. When several entries match, the longest one wins, so
"M5V2" beats "M5V". DEFAULT isn’t a
placeholder or an error case — it’s a real, advertised fallback (“price
for any region we haven’t set a specific rule for”), and every offering and
package must have one. A rule set with no DEFAULT rule is invalid; the
server throws rather than silently pricing at zero.
Here’s a realistic rule set for a package sold in Canada, priced slightly
higher in Ontario, with a USD price for everywhere else:
The region comes from where the booking happens, not who’s buying
This is the rule, and it’s the same everywhere in the platform — bookings, holds, and orders all resolve it identically:
Note what’s not in that table: the client’s billing address, their profile
country, or anything else about who’s paying. Two clients buying the same
PHYSICAL offering at the same Location get the same regional price,
regardless of where either of them lives. Regional pricing is about the
booking’s place, not the buyer’s.
How to tell an order which region
POST /v1/projects/{projectId}/orders accepts three optional fields that
supply the region source, checked in this priority order:
reservationId— the hold this order funds. Preferred. The hold already knows where the booking happens (it’s the same record the eventual bookings are rebuilt from at convert), so pricing the order off it is what guarantees the order and its bookings can never disagree on price. See Hold slots during checkout.locationId— a stored Location, for aPHYSICALbooking.address— the service address, for aTRAVEL_ZONE(in-home) booking. Same structured shape as everywhere else — see Booking addresses.
reservationId → locationId → address → the client’s
default saved address → no region (DEFAULT). A client sets their default
with PUT /clients/me/addresses/{addressId}/default; see
Choose the default address.
Errors from a bad region source
AreservationId or locationId that doesn’t exist is a caller error and
404s, naming the id:
VIRTUAL
hold, for instance — is not an error. It resolves to no region, the
order prices off DEFAULT, and the request succeeds. Don’t treat that as a
bug; a virtual session was never going to have a regional price. (This
“exists but regionless” outcome is specific to reservations — it’s what a
VIRTUAL or address-less TRAVEL_ZONE interval on a hold resolves to. An
existing Location record doesn’t have an equivalent regionless state: once
locationId resolves to a real Location, that’s a LOCATION source, full
stop. The only no-region outcome for locationId is the 404 above, for a
locationId that doesn’t resolve at all.)
The currency you send is the currency you’re asserting
currency in the order-create body is the price you quoted the buyer —
not a label the server takes on faith. The server independently resolves the
region (per the rules above), prices every item against it, and checks that
each resolved currency matches the currency you sent. A mismatch is a
400:
COUNTRY/CA CAD price on a
storefront, then created the order with currency: 'CAD' and no
reservationId / locationId / address at all. With no region to resolve,
the order priced off the package’s DEFAULT rule — which happened to be USD
— and the currency check correctly rejected it. The price data was fine; the
order just didn’t know where the booking was happening.
Confirm what actually priced
Every order item carriespriceRuleId and priceScope
(DEFAULT | COUNTRY | STATE | POSTAL) — read them back and assert they
match what you displayed:
priceScope: "DEFAULT" when you expected a regional price is the tell that
your region didn’t resolve — check that you sent one of the three region
fields, and that the reservation/Location/address you sent actually carries
the country/state/postal you expect.
Country and state codes
country must be ISO 3166-1 alpha-2 ("CA", not "Canada") and
state the ISO 3166-2 subdivision code ("ON", not "Ontario") —
these are what price rules key on. Both are coerced tolerantly on the way
in: "Canada" resolves to "CA", "Ontario" resolves to "ON", and an
alpha-3 country code ("CAN") resolves too.
The two fields fail differently:
-
An unrecognizable
countryis a400 VALIDATION_ERRORon the address, and nothing is written: -
An unrecognizable
state— a misspelling, or a region that doesn’t belong to the given country — is accepted and stored as you sent it. Pricing then ignores it and falls back to theCOUNTRYorDEFAULTrule, silently. The one exception is an offering or package that hasSTATEorPOSTALrules for that country. There, a fallback would charge a price you didn’t intend, so the order is refused with400 UNRESOLVED_SUBDIVISION. Themessagenames the value it couldn’t resolve and the subdivisions the offering prices by:
priceScope of COUNTRY or DEFAULT on an address you expected to
price by state is the tell for a state that didn’t resolve. Send the ISO
code to be sure.
The
path.field prefix (address.country above) is not specific to geo
coercion — every validation failure on this API is reported the same way:
the dot-joined field path, a colon, then the underlying message. Match on
message.includes(...) or split on the first : if you need the bare
reason; don’t match the whole string expecting no prefix.Money is minor units
Everyprice object — on a rule, an order item, or an order total — is
{ amount: integer, currency: 3-letter ISO }, where amount is an integer
in the currency’s minor unit (cents, not dollars). See
Money for the full convention;
regional pricing doesn’t change it — a 47500 CAD rule is $475.00, the
same as anywhere else in the API.
Where to go next
Create a package booking
The order-create step, with a reservationId so the price resolves correctly.
Hold slots during checkout
Why the hold is the preferred region source — it’s the same record bookings are rebuilt from.
Show a package storefront
pricing[] is the full rule set for display — pass the matching region source at order time.
Booking addresses
The structured address shape used for TRAVEL_ZONE region resolution.