Orders And Provisioning turns an current catalogue package into a service record your customer can install and use.
Your integration creates the order, stores your partner order reference, receives the Onyx order state, and guides the customer through activation when the service is ready.
Keep order handling precise. A customer should always know whether the order is created, reserved, provisioning, ready to install, installed, under review, failed, or refunded.
Order Creation
Create an order from an current package in the current catalogue.
Each order should include package ID, partner order ID, customer reference when needed, catalogue version, and an idempotency key for safe retries.
Order creation depends on partner configuration, package availability, market eligibility, payment status, account state, and compliance requirements.
Do not create orders for unavailable packages.
Provisioning
Provisioning prepares the service after order creation.
Current order states are:
- created
- reserved
- provisioning
- esim_ready
- installed
- failed
- manual_review
- refunded
Show the state returned by Onyx instead of inventing a status.
Activation Materials
Activation materials help the customer install service on a supported device.
Activation materials include QR or manual installation information when the order provides them. Treat that information as sensitive.
Do not expose activation materials in public logs, screenshots, support transcripts, analytics tools, or unsecured messages.
Install Guidance
Installation guidance tells the customer what to do next.
Depending on the device and service, the customer may need to install the service profile, select the active line, enable roaming, wait for network registration, or restart the device when instructed.
Use Onyx activation guidance for the service.
Recovery
If installation is interrupted, guide the customer through the recovery path.
Recovery depends on order state, activation state, device state, whether activation materials were already used, and current service eligibility.
Do not tell customers to delete a service profile unless the recovery flow says to do so.
Failed Orders
If an order fails, show the known reason and next step.
Do not retry provisioning repeatedly without a state change or Onyx guidance.
Use reason codes, order state, and support evidence to decide whether the next step is retry, customer action, manual review, refund review, or escalation.