API docs
Sous Chef Onboarding API
Request access

Retries and idempotency

Both write operations on this API, createLocation and addBrandsToLocation, are safe to retry. You do not need to deduplicate on your side. This API has no Idempotency-Key header, because the request body is already the deduplication key.

Why sending the same createLocation call twice is safe

Within your organization, a location is identified by the storeNumber and state you send. Two calls with the same storeNumber and state refer to the same location. The one exception is a location that has since been deactivated: a call for it is rejected with 400.

A repeated createLocation call therefore finds the location the first call created and returns it 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 succeeded.

A retry never edits an existing location

When createLocation finds an existing location for the same storeNumber and state, it returns that location as stored and writes nothing. It does not compare the rest of your request body against what is stored, and it does not update any field that differs.

A retry therefore cannot change a location that may already be live and serving orders, even if you corrected a value on your side before resending. createLocation does not edit an existing location, 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 by an earlier call or by an earlier attempt at the same 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 stores.

This also makes it safe to call addBrandsToLocation again later with a new brand id mixed in with old ones. The old ones report alreadyProvisioned and the new one is provisioned normally, in the same call.

What this does not cover

Idempotency here is about retrying the same call, not about correcting one. This API has no operation that edits a location's or a store's fields after creation. If your system sent the wrong storeNumber or state, do not resend with different values: a different value creates a second, unrelated location. Contact support@yoursouschef.com instead.