Skip to main content

Product Order (Ethernet)

This guide provides a high-level overview of how Ethernet orders are processed and tracked using the Product Order (Ethernet) API.

Because physical Ethernet provisioning involves complex logistics—such as network routing checks, site surveys, and civil engineering—the fulfillment process is primarily asynchronous.

The lifecycle consists of three main mechanisms for tracking your order:

  1. An initial synchronous response: Your immediate confirmation that we received the request.
     
  2. Asynchronous notifications (webhooks): Events sent to your system that provide automated updates on the order's state.
     
  3. Active tracking endpoints: Dedicated GET endpoints to retrieve granular milestones, dashboard totals, and pending customer actions.

The callback URL for receiving asynchronous notifications is configured for you by your BT Account Manager during your initial onboarding. If you need help, please contact your BT Account Manager.
 


Asynchronous processing

When you submit a productOrder via the POST /productOrder endpoint, the API first validates the basic structure of your request and your headers.

If valid, the API immediately returns a synchronous 200 OK  "Process Initiated" response.

  • What it means: We have received your order payload and it has been placed in a queue for processing. 
  • What to do: Your application should listen for this response to confirm the order was submitted correctly.
  • Important: This response only confirms receipt. The order has not yet been formally created in the provisioning system, and you do not have your final Order ID yet.

 


Asynchronous notifications

All updates about the order's actual progress are sent to you via asynchronous webhook notifications. Your system must have an endpoint ready to receive these JSON payloads.

Every order progresses through a series of states. You will receive a notification each time an order or an item within it transitions to a new state.

 

State Definition Next Step
acknowledged Order accepted; Order ID created. Store the Order ID.
inProgress Active engineering work. Monitor via /orderMilestones.
pending Paused for customer input. Check /orderActions.
completed Service is live. Capture the serviceId.
failed / rejected The order cannot proceed. Review error codes in the payload.

 


Track progress via active endpoints

While webhooks push updates to you, the Ethernet API also provides a robust suite of GET endpoints allowing you to actively poll for details, milestones, and dashboard metrics.

You must use the productOrder.id received in the acknowledged webhook to use these endpoints.

Use case 1: Retrieving order details

Retrieve the complete product list, characteristics, and current state associated with a specific order.

Endpoint:

For sandbox testing, use: 

GET https://api-sandbox.wholesale.bt.com/v1/productOrderingManagement/productOrder/{orderId}

In the production environment, use:

GET https://api.wholesale.bt.com/v1/productOrderingManagement/productOrder/{orderId}

 

Use case 2: Tracking engineering milestones

Because Ethernet delivery can take weeks, tracking granular milestones (like "Site Survey Complete" or "NTE Installed") is critical. Retrieve all key engineering and provisioning milestones captured at the order item level. 

Endpoint:

For sandbox testing, use: 

GET https://api-sandbox.wholesale.bt.com/v1/productOrderingManagement/orderMilestones/{orderId}

In the production environment, use:

GET https://api.wholesale.bt.com/v1/productOrderingManagement/orderMilestones/{orderId}

You can further filter this down to specific items using GET /orderMilestones/{orderId}/{orderItemId}.

 

Use case 3: Managing customer actions

If an order pauses because it requires your approval (such as an MCO activity or Excess Construction Charges), you can retrieve these pending actions using the Actions endpoints.

Endpoint:

For sandbox testing, use: 

GET https://api-sandbox.wholesale.bt.com/v1/productOrderingManagement/orderActions/{orderId}

In the production environment, use:

GET https://api.wholesale.bt.com/v1/productOrderingManagement/orderActions/{orderId}

Dashboard totals: You can also retrieve a high-level count of all pending actions across your entire account using GET /orderTotals/customerActions.

 


Best practices and key takeaways

To ensure a robust integration, we recommend the following:

  • Store key identifiers: Always capture the productOrder.id from the initial acknowledged notification.
  • Listen for eventType: Your webhook listener should use the eventType to determine how to process the notification (ProductOrderCreateEvent vs. ProductOrderStateChangeEvent).
  • Parse the state field: Always check the state at both the overall productOrder level and the individual productOrderItem level, as some nested items (like site visits) may complete before the main circuit.
Back to top