Operating notes · Note 07
July 21, 2026 · 7 min read
Partnership / PLG
Partnership / PLG

202 Accepted is
a product decision

A gift card is not ready in the same instant the partner asks for it. Returning 202 tells the truth about that, and it is the first proof the onboarding is willing to call value.

↓ The status that is the signal
01
Async

The card is not
in the response body yet.

Gift card fulfillment in Steller’s published design is asynchronous. The partner posts an order. The wallet is involved immediately. The vendor call, the PIN, and the webhook happen on a path that is not the HTTP request that just returned. The PLG essay says this in product language: gift card orders are async. The 202 is the value signal, not the PIN. The lifecycle is shown after the first order so the partner learns that without a document.

The Complete Story describes the order step in the same spirit and with more mechanism. The partner posts a pre-constructed payload. The system validates, locks the wallet row against race conditions, drops processing onto the background queue, and returns HTTP 202 Accepted with a tracking ID. The track step is a later poll. When the order succeeds, encrypted card codes decrypt and display. Proof is that display. The 202 is the promise that the work was accepted and can be followed.

Choosing 202 is a product decision because the alternative is a lie or a stall. A synchronous 200 with a PIN would deny the queue. A silent hold, with no status, would put the partner back in the old path, where they polled only if they remembered. 202 plus a tracking ID is the contract that the wait is real and observable.

The operator smoke uses the same status for a different audience. Steller’s backend AGENTS.md says not to report success on HTTP 200 alone. An order counts as placed when a poll reaches Completed and the cards array is non-empty. After a config change or restart, ./scripts/smoke-staging.sh runs only after a health probe — the file’s example is http://127.0.0.1:6091/api/health — and the file says not to treat docker compose up -d as that readiness. For partner onboarding the order step is explicit: POST /api/orders must return 202, then GET /api/orders/{id} is polled until Completed. A 200 that skipped the queue would fail the product decision even if it looked healthier in a test.

02
Create and replay

202 is also
what a repeat looks like.

The developer hub is more specific than the essays about which responses are 202. Create order returns HTTP 202 Accepted for new orders and for idempotent replays. The wallet is debited at creation and refunded on failure. referenceId is the partner field for that replay behavior: optional, and strongly recommended. The next note is about that field. Here, the product fact is that a replay is not a different success code. The partner who retries does not have to learn a second status to know the order was already accepted.

That choice teaches async by repetition. The first 202 says the work is in progress. The second 202, on the same reference, says the work was not started again. If replays returned a fresh code, or a body that looked like a second card, the status would stop being a signal and start being a trap. The hub’s rule is the one I will cite: 202 for both.

Debit-at-accept is the other half of the decision. The partner’s balance moves when the order is accepted, not when the PIN appears. The Complete Story’s wallet step exists so that balance is visible before this post — color-coded green, amber, or red. The PLG essay shows the balance, including a zero, before the order so the rejection never has to be the teacher. Refund on failure is how a 202 that later fails does not keep the money. The backend lock on PlaceBambooOrderJob says the job itself does not retry, refunds on failure, and swallows a refund throw. I am not publishing a queue diagram that stitches those sentences into one function. I am saying the partner-visible rule and the operator lock agree that failure returns the debit, and that the job must not “help” by trying the vendor again.

“The 202 is the value signal, not the PIN.”
PLG 2.0 essay · taught by showing the lifecycle
03
How to poll

Two published intervals.
Neither one is a SLA.

The essays and the hub do not tell the partner to poll on the same clock. I will quote both and not average them.

Source
What it says about waiting
Complete Story
The partner polls for status every three seconds. On success, encrypted codes decrypt and display.
Developer hub
Poll every 2–5 seconds until a terminal state: Completed or Failed. The example read is GET /api/orders/{id}.
PLG essay
Status polling is shown live after 202. It does not publish a second interval.

Three seconds sits inside the hub’s 2–5 second range. That is arithmetic, not a decision that one source overrules the other. The Complete Story is describing the 60-second path’s track step. The hub is describing client guidance. A partner integration can follow the hub. The onboarding narrative can keep saying “about every three seconds,” because that is the sentence in the essay. No queue SLA — time-to-PIN, p95, or vendor timeout — is published, so this note does not add one.

Webhooks are a second published way to hear the end of the wait. The hub signs them with X-Steller-Signature, a Base64 HMAC-SHA256 of the raw body using the webhook secret. The events named for orders are order.completed and order.failed. A changelog mention of low_balance is not an order-terminal event, and I will not treat it as one. Webhooks do not replace the poll in the essays. The essays teach the lifecycle by showing the poll. Signature, secret, and HTTPS are security requirements on the hub, not a new onboarding step.

04
Teach the wait

Show the lifecycle.
Do not assign a chapter.

The PLG essay’s principle is to embrace async reality: track, don’t wait. Teaching happens because the status is visible immediately, not because a guide explains HTTP. The partner’s question in that minute is the reviewer’s question — does this work? — not the builder’s question about which code means success. 202 is a yes to “your order was accepted.” It is not yet a yes to “here is the card.”

Confidence before the PIN is the partnership point. The Complete Story says the barrier to a signed partnership is rarely the commercial terms. It is the internal conviction that the thing actually works. A 202 with a tracking ID is evidence the partner can show to someone else in the room: the system took the order, the wallet moved, the status is changing. The decrypted code is the later proof. Asking them to wait in the dark until the code exists spends the conviction the 60-second path is trying to create. Under sixty seconds is the published time to first partner value, and the value in that sentence is a successful API transaction the path can track, not a claim that every PIN is on screen before the minute ends. The essays do not publish a separate time-to-PIN.

TTV-Order, in the PLG essay, is time from auth to the first 202. TTV-Track is time from that order to the first visible poll. The product decision puts 202 in the metric on purpose. If the metric waited for the PIN, async work would look like onboarding failure.

05
Terminal

A short list
of what “finished” means.

Finished, from the texts this note is allowed to use:

  • Accepted: HTTP 202 for a new order, with a tracking ID in the Complete Story’s account.
  • Accepted again: HTTP 202 for an idempotent replay, not a second order, on the hub’s account.
  • In flight: poll. Every three seconds on the essay path, or every 2–5 seconds per the hub, until the state is terminal.
  • Completed: the hub’s success terminal. The Complete Story then shows decrypted card codes.
  • Failed: the hub’s other terminal. The wallet is refunded on failure. The Bamboo job does not retry.
  • Optional listen: order.completed or order.failed, signed, not instead of understanding 202.

Rate limits can interrupt the poll. One hundred requests per minute per API key, and ten requests per second on orders, are the hub’s published guards. A 429 may be plain text. Use Retry-After. Retry the order with the same referenceId so the retry stays inside the 202-for-replay rule. None of that is a reason to treat 202 as a soft error. It is a reason to keep polling like a client that believes the status.

202 Accepted is the product saying: the work is real, the wait is visible, and the card is a later state. That is a better first truth than a PIN the architecture cannot honestly return yet.

Next in the series
Note 08 · Operating notes
Idempotency for Gift Card APIs
referenceId for partners, and a separate vendor Idempotency-Key.
Read the essay →