Handle Asynchronous Orders

Many Connect order flows do not finish within the initial POST /orders request.

Your integration should treat order creation as the start of a lifecycle, not as the final confirmation that provisioning is complete. The correct pattern is:

Create the order
Store the returned order.id
Wait for webhook events
Retrieve the Order or related resource when you need the latest state

Your backend -> POST /orders
Connect accepts the order and starts background work
Connect -> webhook events -> your endpoint
Your backend -> GET /orders/{order-id} when it needs latest state

Tip: Do not build your integration around aggressive polling alone. Webhooks should be the primary signal for order progress and completion.

Core endpoints and events

Endpoints:

Events:

What to persist when you create an order

When you call Create Order, store at least:

order.id
your internal correlation identifier
the business context for the order, such as account, subscriber, product, or subscription
the Idempotency-Key used for the request

This gives you a stable way to:

reconcile later webhook deliveries
avoid duplicate business actions during retries
retrieve the latest order state when needed

Handle common outcomes

Order completed

When you receive Order Completed:

mark the order as completed in your system
update the related business object using identifiers from the event payload
retrieve the order or related resource if you need the latest embedded data

Completion means the order lifecycle finished successfully. It does not always mean the end user has already completed the next human step, such as installing an eSIM.

Order failed

When you receive Order Failed:

mark the order as failed
capture the failure details available in the event or retrieved order state
surface the failure to operations or customer support when needed
decide whether your business flow should retry, stop, or ask for correction

Order on hold

Some flows intentionally pause. When you receive Order On Hold:

do not treat the order as failed
store the paused state
complete the missing external action
call Resume Order when the workflow is ready to continue

This pattern is especially important for porting-based journeys.

In many cases, you will need more than the order record itself.

Useful follow-up resources:

Use these when you need to confirm the final live state after an asynchronous change, especially for:

activation
plan change
cancellation
top-up
SIM swap

Reliability

For idempotency, duplicate handling, and out-of-order strategies, see Configure Webhooks — Recommended partner behavior. For broader production guidance, see Go to Production.

On this page