Overview#
Like the rest of Nitrogen, the ordering process is asynchronous. The initial submission will result in an ID being returned and remaining updates on the order will be delivered as asynchronous callback messages delivered to your subscription endpoints.
Synchronous Initial Validation#
At the time of initially submitting the order payload, Nitrogen performs some synchronous validation checks for things that are possible to check immediately (e.g. valid payload, valid product offer, valid combination of values in payload etc.).
Initial Validation Failure#
If the initial validation fails, the submission will be rejected immediately with a 422 Unprocessable Content validation error as the synchronous response. No order resource will be created in Nitrogen and no order id will be generated.
In this instance, you should check and resolve the issues in the validation error and try again to achieve a successful submission.
Initial Validation Success#
If the initial validation passes, Nitrogen will create an order resource in New status and return a synchronous 201 Created response with a unique order ID in the response payload.
The unique order ID will then be used to identify the order in asyncronous callback messages, and can also be used to query the order via the GET order endpoint if required.
Order Lifecycle and Status#
Once an order has passed initial validation and been created in Nitrogen, it will then go through a series of additional validation and verification steps, including ongoing validation with the upstream provider/s (e.g. NBN).
Nitrogen will then manage the status and sub-status of the order from its initial status New through to completion or rejection/cancellation through a series of status and sub-status changes.
Status and Sub-Status#
The status of the order describes largely where it is at in the order lifecycle.
The sub-status allows more information to be provided as to the reason for the current status.
The below table outlines the possible status and sub-status combinations for an order, and what they generally mean. Note, new combinations may be added as required and some statuses and sub-statuses won't apply to some orders.
| Status | Sub-Status | Description |
|---|---|---|
| New | New | Order has been created, not yet submitted to upstream provider (if required) |
| New | Awaiting Upstream | Order has been submitted to upstream provider, not yet accepted by them |
| In Progress | Awaiting Upstream | Order has been accepted and is in progress with an upstream provider |
| In Progress | Wholesaler Action | Order is in progress within Nitrogen |
| Awaiting Tenant Action | Appointment Required | Order is awaiting you to attach a valid appointment |
| Awaiting Tenant Action | Appointment Reschedule Required | Order is awaiting you to reschedule its appointment |
| Awaiting Tenant Action | Provide Information | Order is awaiting you to submit required information or take requested action |
| Rejected | Rejected By Upstream | Order is rejected due to upstream provider rejecting it |
| Rejected | Rejected By Wholesaler | Order is rejected by Nitrogen |
| Cancelling | Awaiting Upstream | Order is pending cancellation with upstream provider |
| Cancelling | Wholesaler Action | Order is pending cancellation within Nitrogen |
| Cancelled | Cancelled By Tenant | Order was cancelled at your request |
| Cancelled | Cancelled By Wholesaler | Order was cancelled by Nitrogen |
| Cancelled | Cancelled By Upstream | Order was cancelled by upstream provider |
| Cancelled | Cancelled By Failed Auto Appointment | Order was cancelled due to Nitrogen being unable to automatically book an appointment |
| Complete | Complete | Order has completed successfully |
Order Webhook Events#
Throughout the life of an order, many events occur and asynchronous messages will be delivered to your subscription endpoints automatically.
The following events are currently sent for orders:
- order.acknowledged.event
- order.accepted.event
- order.completed.event
- order.planned-remediation-date.event
- order.failed.event
- order.rejected.event
- order.cancelled.event
- order.awaiting-cancel.event
- order.disconnect.in-progress.event
- order.disconnect.failed.event
- order.disconnect.awaiting.event
- order.provider-action-required.event
- order.auto-appointment-failed.event
- order.appointment-required.event
- order.service-test-completed.event
- order.appointment-reschedule-required.event
- order.appointment-rescheduled.event
- order.more-time-accepted.event
- order.more-time-rejected.event
- order.rsp-action-completed.event
- order.rsp_action-required.event
- order.device-details-required.event
- order.information-required-reminder.event
- order.nbn-action-completed.event
- order.shipment-in-transit.event
- order.amend-failed.event
- order.amend-in-progress.event
- order.amend-accepted.event
- order.amend-rejected.event
For detailed information on each event, consult the API specification.
New event types will be added as required and will be added to the documentation as they are added.
In addition to the above events in the context of an order resource, related resources will also receive events that closely correspond to the ordering lifecycle. For example, updates to appointments, activation of the service that an order creates etc.