Skip to main content
A request timed out and you do not know whether it landed. This page tells you which calls you can send again as they are, which ones quietly create a second record when you do, and what to read instead of guessing.

What you’ll do

1

Send a key where the platform takes one

Two appointment writes require an Idempotency-Key; nine billing writes accept one.
2

Look before you create

GET /v0.1/patients?email=<address> is the de-duplication read — there is no upsert.
3

Re-send only what is safe

Reads are safe. A create without a key is not, and a key already spent on a finished attempt replays that attempt instead of making a new one.
4

Report a duplicate you already made

Two patients, two ids, one email — keep one, and ask OpenLoop to remove the other. You cannot delete it yourself.

Which calls are safe to send again

Recipe · Send an Idempotency-Key where the platform takes one

Idempotency-Key is a request header, and the published reference declares it on twelve write operations. On two of them it is required: Omitting the header on either appointment write is rejected before any body or id validation — a PATCH at an id that does not exist still answers the key, not a 404:
Locked by check idempotency-key-required-on-appointment-writes.

The key is not the same shape everywhere

The reference asks for a different kind of value per family, and the difference matters:
  • Appointments — a fresh UUID per action. The key is global to your integration, not scoped to an endpoint or an appointment, so a key already spent on a booking will replay that booking if you send it on a later cancel or reschedule. Failures are stored too: change the request or search for a new slot, and you need a new key.
  • POST /v0.1/subscriptions — a deterministic, order-scoped value such as initial-subscription:{provider_customer_id}:{order_id}, so that re-sending the same attempt de-duplicates: a client that mints a fresh random value on retry creates a second subscription. But the key is per attempt, not per order. Reusing it after the attempt has reached a terminal outcome replays the stored response instead of doing the work again — a retry after a 400 decline returns that same 400, even when the patient has supplied a replacement card, and an items array changed under an unchanged key is rejected as an idempotency conflict rather than retried. Mint a new key for a genuinely new purchase attempt. The replay window (roughly 24 hours) also outlives the subscription’s own incomplete_expired deadline (roughly 20 hours), so a key can still be replaying a decline long after the attempt it belongs to has expired. Payment failure documents that 400 (a declined off-session charge on POST /v0.1/subscriptions) and what it leaves behind.
  • POST /v0.1/checkouts/sessions — an opaque random value such as a UUID.
A replayed response comes back with x-idempotency-replayed: true and the original body, and the stored response lives for roughly 24 hours.
The header semantics above — the replay window, x-idempotency-replayed, the per-family key advice, and the replay of a stored 400 decline — are the published reference’s own description of these parameters, read 2026-09-11. The checks on this page exercise the absence of a key, which is what the harness can send; they do not measure replay behaviour.

Recipe · De-duplicate a patient before you create one

There is no upsert and no key on POST /v0.1/patients, so the read is the de-duplication step:
A non-empty items array means you already created this patient — take items[0].id rather than posting again. Percent-encode the address. A raw + in the query string arrives as a space and the filter rejects it:
Locked by check dedup-by-email-before-create.

Recipe · What a repeated create actually does

Sending the same POST /v0.1/patients twice returns 201 twice, with two different ids. The email filter then returns both records. Nothing rejects the duplicate — de-duplication is yours.
So write your own mapping from your identifier to the platform id before you send the create, and reconcile it against the email read when a request times out. There is no partner delete to undo the duplicate. Keep using the id you mapped, and ask your OLH implementation contact to remove the other — say whether intake was submitted against it, because a completed submit has already created an encounter. See User migration. The same holds for a duplicated /questionnaire-responses create: correct an in-progress response with PUT /v0.1/questionnaire-responses/{id} (published) rather than posting again, and ask OpenLoop to remove a duplicate.
Locked by check repeat-create-makes-a-second-patient.

Recipe · Read after a write

The read after a write can be stale. Immediately after a patient write answered 200, GET /v0.1/patients/{id} was observed still returning the previous state, and the new state a moment later (verified on staging 2026-09-11; the write observed was a patient delete, which is no longer partner-callable, and the lag has not been re-measured on PUT). Read-back is eventually consistent, so a read that still shows the old state is not proof your write was lost. Wait and read again before you re-send anything.

Recipe · Why a repeated subscription update adds a line item

PUT /v0.1/subscriptions/{provider_subscription_id} takes no Idempotency-Key, and its items array is addressed by id: An upgrade written as items: [{ provider_price_id: "price_…" }] therefore adds a line every time it is sent. Retry it after a timeout and the subscriber ends up paying for two of the same thing. After a timeout on a plan change:
  1. GET /v0.1/subscriptions/{provider_subscription_id} and compare items against what you meant to send.
  2. If the change did land, stop — the response to a PUT is the subscription, not the payment result, so also read status and /invoices?status=open per Upsell and cross-sell.
  3. If you must re-send, address the existing item by provider_item_id rather than adding a price.
The items semantics above are the published request schema for this route, read 2026-09-11, not something the checks on this page measured — exercising it needs a paid subscription in your tenant.

What comes back

Gotchas

A replayed key is not a second attempt. Retrying POST /v0.1/subscriptions under the key from a declined attempt returns the stored 400, so a replacement card looks as though it failed too, and an edited items array comes back as an idempotency conflict. Scope the key to the attempt, not to the order: a new card or a changed basket is a new key. See Payment failure for what to read and what to tell the patient. (Published reference, read 2026-09-11 — not measured here.)
A read immediately after a write can still show the old state. Do not treat a stale read as evidence that your write was lost and re-send it — for a create, that is how you get two patients. Read again after a pause, and reconcile on ?email= rather than on a single read — that filter is itself a collection read and can trail a create by a moment.
The clinical writes take no idempotency key at all. POST /v0.1/patients, /questionnaire-responses and /reservations declare no such header in the published reference, so the platform has nothing to de-duplicate on. Guard these client-side.
An appointment key is global to your integration. Reusing a key that was already spent on a booking will replay that booking when you send it on a later cancel or reschedule. Mint a fresh UUID per action; never derive one from the appointment id.
Every response carries request_id, success or failure. Log it on the first attempt as well as the retry — it is what an escalation is keyed on. See Errors for the envelope.

Integration flow

The happy path these retries interrupt: create the patient, submit intake, pay

Appointments and scheduling

The two writes that require an Idempotency-Key before they will run at all

Upsell and cross-sell

The subscription update whose retry adds a line item

Payment failure

What a 400 decline on POST /v0.1/subscriptions leaves behind, and why retrying it under the old key replays it

Errors

The error envelope, request_id, and what each status means