Possible breaking changes in Booking and Address Check APIs

Production date: 23.09.2026

Summary
Refinement of error handling in the Carrier/Retailer delivery check to give API consumers more precise diagnostics.

Affected endpoints

• POST /ws/json/parcel/booking/v-1/book — Book a shipment

• PUT /ws/json/parcel/booking/v-1/orders/{messageNumber} — Full replace of an existing order

• PATCH /ws/json/parcel/booking/v-1/orders/{messageNumber} — Partial update of an existing order (JSON Patch, e.g. changing the consignee delivery address)

• POST /ws/json/addressCheck/single/v-1/find — Validate freight product for a single address

• POST /ws/json/addressCheck/single/v-1/dates — Valid delivery dates for an address (carrier-support changes only)

• POST /ws/json/parcel/retailerdelivery/v-1/returnCustomerPackage/{transporterId}/{servicePointId}/{parcelNumber} — Customer-initiated retailer return

• POST /ws/json/freightcoverage/v-1/servicepoints — Servicepoint coverage for a zip (carrier-support changes only)

• POST /api/flow/orders/v2 — Book an order (v2 API)

• PATCH /api/flow/orders/v2/{trackingReference}/orderparties/{orderPartyType} — Update an order party (e.g. consignee address) on an existing order

• PATCH /api/flow/orders/v2/{trackingReference}/shipment — Update shipment details on an existing order

• POST /api/flow/orders/v1/addresscheck — Validate freight product for a single address (v1 orders API)

Breaking changes

• API errorCode no.retailer.found has been renamed to no.active.retailer.product. The new name reflects the actual check being performed (isRetailerActiveOnDatesForRetailerProduct) rather than a generic "no retailer" condition. Surfaces on the booking, order-update, single address check and retailer-delivery endpoints when the freight product has retailerDeliveryCheck = true. Consumers that match on the string no.retailer.found must be updated.

New functionality

• The existing no.carrier.supporterrorKey can now include a no.address.match value in its errorMap, letting consumers distinguish "no carrier supports this address" from other carrier-support failures without introducing a new top-level error code.

Impact

• Clearer feedback when a booking or address check fails due to an inactive retailer product versus a generic retailer lookup failure.

• Address-related carrier-support failures can be identified separately from other carrier-support failures, reducing troubleshooting time on the booking, address check and freight coverage endpoints.