Retries and idempotency
Both write operations on this API — createLocation and addBrandsToLocation — are safe to retry. Not "safe if you deduplicate on your side": safe because of how each one is built. There is no Idempotency-Key header anywhere on this API, because there is nothing an extra header would add — the request body is already the deduplication key.
Why sending the same createLocation call twice is safe
A location's code is derived deterministically from the storeNumber and state you send, plus a prefix tied to your organization — not assigned from a counter. Two calls with the same storeNumber and state always compute the same code, and that code is unique across the whole platform.
So a repeated createLocation call does not race a sequence or collide by chance: it recomputes the code, finds the location it already created, and returns that location with created: false instead of creating a second one. Retry on any failure — a timeout, a 5xx, a dropped connection — without first checking whether the first attempt actually landed.
A retry never edits an existing location
This is the part worth reading twice: when createLocation finds a location the code already identifies, it returns that location as stored and writes nothing. It does not compare the rest of your payload against what is stored, and it does not update any field that differs.
That is deliberate, not a missing feature. If a retry silently patched fields that differ, then a partner correcting a typo in their own system and resending would silently mutate a location that may already be live and serving orders — from a call whose only intent was "make sure this location exists." Editing an existing location is not something this operation does, on a retry or otherwise.
Why sending the same addBrandsToLocation call twice is safe
Each brand in the request is provisioned independently and only once. A brand already provisioned at the location — whether from an earlier call or from earlier in the same retried call — comes back with status: "alreadyProvisioned", and nothing is written for it. Nothing is duplicated: not the brand location, not the menu copy, not the per-platform stores.
This is also what makes it safe to call addBrandsToLocation again on purpose, weeks later, with a new brand id mixed in with old ones — the old ones report alreadyProvisioned and the new one provisions normally, in the same call.
What this does not cover
Idempotency here is about retrying the same call, not about correcting one. There is no operation on this API today that edits a location's or a store's fields after creation. If your system sent the wrong storeNumber or state, the location that resulted is correct given what you sent — get in touch rather than resending with different values, since a different value computes a different code and provisions a second, unrelated location.