Idempotency for
gift card APIs
A retried order can debit a wallet twice or mint a second card. Steller publishes two different keys for that risk. They are not the same field, and this note will not pretend they are.
The bug the old
architecture already knew.
In Built From the Rubble the session-starting bugs were orders completing while wallets were not debited, or debited twice. That was a visibility problem: the agent could not see both sides of an implicit event. Idempotency is the partner-facing version of the same money problem. A client that times out and posts again must not buy a second card or move the wallet a second time.
Gift cards make the retry ordinary. The order is asynchronous. 202 Accepted returns before the PIN exists. A partner who does not see a code yet will send the request again. A poll interval — every three seconds in the Complete Story, every 2–5 seconds on the developer hub — exists so they do not have to. When they retry anyway, or when a 429 tells them to, the second post has to land on the first order.
The pre-pivot system could not show an agent that chain. The current public contract can show a partner the field that makes the chain safe. The field is referenceId. I am not describing a database unique index. No such schema detail is published, and inventing one would turn a product rule into a storage design the record does not contain.
Optional, and
strongly recommended.
developers.steler.org is the source for the partner rule. Idempotency is via referenceId. The field is optional and strongly recommended. Create order returns HTTP 202 Accepted for a new order and for an idempotent replay. The wallet is debited at creation and refunded on failure. The example write is POST /api/orders. The example read is GET /api/orders/{id}.
“Optional” and “strongly recommended” are both the published wording. I will not upgrade optional to required, and I will not shrug off the recommendation. A partner can call the API without the field. A partner who retries without it does not get the replay behavior the hub describes. The 60-second path’s pre-constructed payload, in the PLG essay and in the Complete Story, is the onboarding’s way of not leaving that field to chance on the first order. I am not quoting a sample JSON body. The hub’s collection is claimed; the file was not part of the record used here, so no sample payload is invented.
A replay that still returns 202 is the product decision from the previous note, applied to duplicates. The partner does not learn a second success code. They learn that the same reference is the same order. Terminal states remain Completed and Failed. Failure refunds the debit. PlaceBambooOrderJob does not retry the vendor job on its own. Partner retries and job retries are different levers, and only the partner lever is referenceId.
The same reference returns 202 again. It does not start a second order.developers.steler.org · create and idempotent replay
A 429 is a reason
to reuse the reference.
The hub publishes two limits. One hundred requests per minute per API key. Orders also have a ten-requests-per-second guard. A 429 may be plain text, so a client that only parses JSON will miss it. The published recovery is Retry-After, then retry the order with the same referenceId.
That interaction is the whole point of calling the field strongly recommended. The limit is allowed to fire. The poll guidance of every few seconds, plus dashboard traffic, plus a retry, can approach a limit without anyone “load testing.” If the retry generates a new reference, the guard has created a second order. If the retry repeats the reference, the guard has delayed the same order. Idempotency is what makes the rate limit safe to hit.
Auth sits next to this and is easy to mix up. Partner API calls use the x-api-key header. The dashboard password is not that key. Staging and production use different base URLs and different keys. A retry against the wrong environment with a reused reference is not the replay the hub is talking about; the keys are not shared across environments. The Complete Story’s auth step — credentials in, a JWT back — is a different published sentence, and this note does not merge it into the API-key header.
referenceId, and no claim about what happens if two different partners choose the same string. Those behaviors are not in the cited pages.The vendor key
is a separate lock.
Steller’s backend AGENTS.md contains a second idempotency rule, and it is not a synonym for referenceId. Bamboo vendor calls always send an Idempotency-Key. The job that places those calls, PlaceBambooOrderJob, does not retry, refunds on failure, and swallows a refund throw. Hangfire WorkerCount stays at 2 for Bamboo and is not increased. Those locks are operator rules. They stop an agent from “simplifying” the vendor client or speeding the queue into duplicate provider orders.
Nothing in the published essays or the hub says that the partner’s referenceId is forwarded as Bamboo’s Idempotency-Key. I will not say that. A partner integrates one field. The platform’s vendor call carries another. Both exist because a gift card request can be repeated. They are documented in different places, for different callers.
referenceId on POST /api/orders. Optional, strongly recommended. Replay returns 202. On 429, retry with the same value.Wallet safety is the outcome both rows are about. Debit once at creation. Refund if the order fails. Do not let a retry, a worker-count “improvement,” or a missing vendor key create a second fulfillment. The Complete Story adds one mechanism on the accept path: the wallet row is locked against race conditions when the order is posted. That is a published phrase, not a locking algorithm. I am leaving it as a phrase.
Use the glossary’s names.
Do not invent the price.
The hub glossary lists, among its terms, face value, SKU, referenceId, and idempotency. This note uses referenceId the way the API reference uses it: the partner idempotency field. It uses SKU the way the onboarding essays use it: the thing the old path made a partner hunt for, and the thing the PLG path pre-filters to ready-to-order products. Face value is named in the glossary. A definition that separates face value from a partner price was not part of the material quoted for these essays, so I will not write one. Partners should take that distinction from the glossary itself, not from a paraphrase.
The other partner rules that keep idempotency from depending on secrets in a blog post are already public. Store the API key securely. Do not share it across environments. Use HTTPS in production. Keep the webhook secret; signatures use X-Steller-Signature, Base64 HMAC-SHA256 of the raw body. IP allowlisting is optional. Staging uses a sandbox vendor and test funds, with real API flows, and a separate key. Production credentials follow a successful staging end-to-end run. None of those sentences includes a live base URL or a secret, and this note will not add them.
Idempotency for this API is a partner habit plus an operator lock. Send referenceId. Expect 202 on the first post and on the replay. On a limit, wait and send the same reference. Trust that vendor calls carry their own key, without assuming you control that key’s value. The double debit the agents used to miss is the bug this field is published to prevent.