Order lifecycle

An order wraps the payment; each order contains an order item that represents the actual gift being issued and delivered. The two have separate statuses.

Order status

For API orders paid from a prepaid balance, orders are typically COMPLETED immediately at creation.

Order item status

Tracking orders

There are no webhooks today — poll the order query APIs to track progress:

• GET /v1/orders/{id} for a single order.
• GET /v1/orders with filters (order_item_status=PENDING, date ranges, external_reference_id, etc.) for batch reconciliation. Note that page and element_size (max 500) are required on this endpoint — e.g. GET /v1/orders?order_item_status=PENDING&page=0&element_size=100.

Practical guidance:

• Most digital orders complete within seconds to a few minutes. Poll at a modest interval (e.g. every 30–60 seconds for the first few minutes, then back off) and stay within the rate limit.
• Items in a recipient-provided flow can stay PENDING for days — until the recipient accepts or the acceptance link expires. Check delivery.recipient.acceptance.expiry_date rather than treating long-PENDING items as failures.
• For reconciliation jobs, query GET /v1/orders filtered by your external_reference_id values rather than storing only SodaGift order IDs.

Cancellations

Gift card orders are final — once placed, they cannot be cancelled. Double-check the product, amount, and recipient before ordering, and always pass an external_reference_id so retries can never create accidental duplicates. Test your integration in the Sandbox first.