Bring Booking API: Adding Idempotency, Step by Step

Build a client-side idempotency layer for Bring's Booking API so retried POST /api/create calls never double-book or double-label a shipment.

Share

Bring's Booking API has no server-side deduplication. If your HTTP client retries a POST to /booking/api/create after a timeout, you don't get a replayed response, you get a second shipment, a second label, and a second EDI pre-notification. This post walks through building a client-side idempotency layer in front of that endpoint, so a network blip never turns into a duplicate shipment booking you have to chase down and cancel manually.

Why Bring's Booking API needs a layer you build yourself

Bring's documentation is explicit about what correlationId is for, and it isn't retry safety. The field is described as an identifier to correlate packages which belong to the same order. That's a grouping key for multi-package consignments, not a token Bring stores and checks against incoming requests to collapse duplicates.

Compare that with the pattern you'll find on comparable booking and payment APIs: the client generates a key, sends it in an Idempotency-Key header, and the server persists the first response against that key so a retried request with the same key gets the original result back, not a new side effect. Bring has no equivalent header and no documented server-side store for one. If you want idempotent shipment booking against this API, the idempotency store has to live on your side of the wire, not Bring's.

What you need before starting

Have these in place before you write any retry logic:

  • A Mybring user account with an API key generated from the API page, and a customer number with booking rights attached to that user.
  • Three headers on every call: the account email as your UID header, your generated API key, and a client URL header identifying your integration, alongside the standard X-Bring-Test-Indicator sandbox flag.
  • The current base URL. Bring is phasing out API access on the mybring.com booking base URL and asks integrators to use https://api.bring.com/booking/api instead.
  • Confirmation you're off SOAP. The SOAP endpoint was deprecated from 10 May 2024, with a migration deadline to the JSON/XML over HTTP endpoints. If a legacy integration is still on SOAP, fix that first.
  • A datastore you control, Redis or a Postgres table, to hold your own idempotency records: key, request hash, response body, status, and an expiry.
CapabilityTypical modern booking/payment APIBring Booking API
Client-supplied dedup keyDedicated Idempotency-Key header, server-storedNot published
Grouping key for multi-package ordersOrder or cart IDcorrelationId per package
Sandbox toggleOften a separate hostX-Bring-Test-Indicator header on the same host
Error taxonomyVaries by vendorGET /api/errors returns the current code list, e.g. BOOK-VALIDATION-001, BOOK-AUTHORIZATION-001

Building the idempotency layer, step by step

  1. Generate a client-side key per booking attempt. Before any network call, create a UUID in your application code. This is the key Bring doesn't give you, and it's the only thing standing between a timeout and a duplicate booking.
  2. Persist the key in "pending" state first. Write the key, a hash of the request payload, and a "pending" status into your idempotency store in the same database transaction as the business record (the order or shipment row). If your process crashes before the HTTP call fires, you still have evidence of intent to book, which matters for reconciliation.
  3. Build the request body. Populate consignor, consignee, and the packages array. If multiple packages belong to one order, set the same correlationId value across all of them, per its documented purpose of correlating packages within an order. Attach value-added services by their id and the relevant customerNumber.
  4. Set headers and sandbox flag explicitly. Use Accept: application/json and Content-Type: application/json. Bring has recently added an HTTP header requirement for test orders on the Booking and Pickup APIs, which reinforces that this is a header flag, not a separate stage host. Make the sandbox flag an explicit, tested config value per environment, because a missing or wrong flag doesn't error, it just books live.
  5. Send the POST to /booking/api/create. On a 2xx response, immediately write the full response body, shipment number, tracking reference, label archive URL, against your idempotency key, before returning control to the calling code. If your process dies between receiving the 2xx and writing it down, you've lost the one piece of information that tells you booking already happened.
  6. On network failure or timeout, check your own store before resending. Never construct a fresh request on retry. Look up the idempotency key. If it's still "pending" past your SLA, don't guess, reconcile via the Tracking API using whatever reference you have, before you ever call the booking endpoint again for that logical booking.
  7. Confirm success by content, not just status code. A 2xx with an empty label field or missing tracking reference is a failure in practice, even though the HTTP layer says it worked. Treat "200 but no label" as a case for your reconciliation path, not a success.

You'll know the layer works when a deliberately killed connection mid-request, simulated with a proxy timeout, never produces a second shipment number against the same business order. That's the test to run before you trust this in production, not after.

Failure mode: the client times out after Bring already booked

This is the scenario the whole layer exists for. Bring receives the request, creates the shipment, generates the label and the EDI pre-notification, and the HTTP response never makes it back to your service, dropped connection, proxy timeout, whatever. From your application's point of view, the call failed. From Bring's point of view, it succeeded.

If your retry logic just builds a new request and POSTs again, you get a second real, billable shipment. A fresh correlationId doesn't help here, it only groups packages within one order; it has no power to collapse two separate order submissions into one. Bring has no header for you to resend that would make it recognise "I already did this."

The fix is the store you built in step 2. On any ambiguous outcome, your own idempotency record is authoritative, not the absence or presence of an HTTP response. Query the Tracking API or your order history by the reference you control before you ever re-post the same logical booking. It's slower than blindly retrying, by design.

Worth building into the same reconciliation path: service codes don't stay valid forever. Bring has been commercially discontinuing certain service and country combinations from 1 January 2026, with API support following shortly after. Validate against the current error-code list at GET /api/errors rather than caching a product list indefinitely, so a decommissioned service shows up as a clean validation error instead of a mystery failure mid-retry.

Sandbox/production drift and a 2026 regulatory wrinkle

Because the sandbox toggle is a header and not a separate base URL, treat X-Bring-Test-Indicator as a first-class deployment variable in your config management, the same way you'd treat a feature flag or a per-tenant setting. A header that silently defaults to the wrong value in one environment is how test orders end up live, or live orders end up untracked in sandbox.

Two payload-shape changes are worth building schema checks around now. From 10 April 2026, the Booking API supports passing Norwegian goods in transit (NVIT) information when ordering a shipment, which is a new field your validation needs to accept, not reject. And separately, from 3 July 2026, goods sent B2C from outside the EU face new customs payment requirements, with certain Norway-origin services to several EU countries only purchasable prepaid. If your integration hasn't been updated to handle the IOSS reference field correctly for the affected lanes, bookings on those routes will start failing validation, not silently succeeding with a wrong customs status, which is at least the safer of the two outcomes. Still, don't find out from a support ticket. Pull the revision history into your release checklist.

Where this fits in a multi-tenant carrier integration platform

None of this is specific to Bring in spirit, only in the header names and field semantics. Any carrier adapter that doesn't guarantee server-side deduplication needs the same wrapper: a client-generated key, a durable pending-then-complete record, and a reconciliation path that checks state before it ever retries a mutating call. That logic belongs once in a shared library at the adapter boundary, not reimplemented per carrier by whoever touched that integration last.

This is also, less visibly, one of the higher-value jobs a multi-carrier platform does. Whether you're looking at Cargoson, nShift, Shipmondo, or ShippyPro, each one is solving the same underlying problem: grafting reliable deduplication onto a set of carrier APIs that don't all agree on how, or whether, to provide it themselves. A clean reference design keys the idempotency store by tenant, carrier, and client-generated key, sitting in front of every adapter, Bring included, rather than treating each carrier integration as its own island with its own retry logic.

If you're building this today, start smaller than you think you need to: get the pending-state write and the post-2xx write working and tested against a deliberately broken connection before you touch anything else. The rest of the resilience work, backoff tuning, dead-letter handling, observability on booking latency, sits on top of that foundation, not instead of it.