Polling for Status

Placements are fulfilled asynchronously. After you launch an order, its placements move through the placement state machine over minutes to days. In v1 you observe that progress by polling — there are no webhooks yet.

What to poll

• Whole order — GET /rest/api/v1/orders/{order_id} returns the order plus every placement with current status and live pricing. Use this for a full snapshot.
• Single placement — GET /rest/api/v1/orders/{order_id}/placements/{placement_id} returns just that placement. Use this to cheaply watch one placement without pulling the whole order.

Both are read-only, require only the orders:read scope, and never affect billing.

How often to poll

Because placements advance on human/editorial timescales, poll infrequently — every few minutes is plenty, and backing off further (e.g. every 15–30 minutes) once an order is well underway is friendlier to the rate limits. Poll individual placements rather than the whole order when you only care about a subset.

A reasonable pattern:

1. After launch, poll the order every ~1–2 minutes while placements are still transient.
2. Once a placement is close to terminal (APPROVED), you can poll it individually.
3. Stop polling a placement once it is terminal.

Interpreting terminal states

Stop polling a placement once it reaches one of these:

An order reaches COMPLETED once all its placements are terminal (and REJECTED / REFUNDED at the order level for the failure/refund cases). See Credits & Billing for how refunds settle.

Webhooks