Purchases and order status

How a purchase works, when money is charged and returned, and where to get the key.

Steps

1. Optionally check availability right before buying: GET /products/{id}/availability.
2. POST /purchase/{productId} with an idempotencyKey. The order is created and its price reserved from the balance in one operation. If the balance is short, no order is created (402).
3. A manually fulfilled product completes immediately. An automatically fulfilled product is bought from the supplier; after the key arrives the order is checked for a short while and only then becomes completed.
4. The key is in the key field of the purchase response or GET /orders/{id}. Webhooks never contain it.

Statuses

completed, failed and cancelled are final: the status never changes again.

The 202 response

If the supplier purchase doesn't finish within about 50 seconds, the API answers 202 with the order in pending. This is not an error and not a reason to buy again: the order keeps going. Learn the outcome from the webhook or GET /orders/{id}. In rare cases, when the outcome has to be double-checked, the order stays pending longer — the money stays reserved all that time and comes back if the order is not fulfilled.