Introduction
Note: In the descriptions below the term "product offering" is used to describe what can be ordered from the available catalogue to provide a product. A "product" is an instance of a product offering sometimes referred to as an asset or service. So productOffering.id is the catalogue id of a product offering and product.id is the id of a provided product or asset.
Use this API to:
- Create a product order to
- Amend (an open order)
- Request a cancellation (of an open order)
This tutorial introduces all order types, and explains how to manage orders and track them via product order state change events (KSUs).
To see how this API forms part of the wider Broadband One order process, click the diagram below.
Prerequisites
Every API request requires an OAuth 2 bearer token.
First time working with our APIs?
- Register on this developer portal
- Create a Broadband One app for a Consumer Key and Consumer Secret
- Read the OAuth 2 reference documentation to generate your bearer token.
Explore payload examples
Preparing for order updates (KSUs)
You'll need an API supporting the OAuth 2 Client Credentials Flow, on a service to which we can POST order updates (KSUs).
During your onboarding to use the production environment you'll need to provide a client ID and secret for your endpoint.
The OAuth 2 Client Credentials Flow is also used to authorise inbound API requests.
Provide
Provide orders support provision of a product to an end user via a number of "journey types". Journeys include new line provide, stopped line start, working line takeover and provider to provider migration (with or without change of access technology).
“New line provide” seeks to provide the product from scratch or, for fibre, on an existing ONT.
“Migration” is the transfer or switch of an existing end user and their product from their current provider with a possible change in technology.
Copper access based broadband products have two additional new provide journey types related to the use of existing copper lines to avoid the need for a customer site visit and thus reduce the lead time to provide.
“Start of stopped line” targets an existing line to a customer’s premises which is currently not being used to provide a product.
“Working line take over” targets an existing line where the current user is ceasing their product leaving it free to be adopted by a different end user at the same premises.
This example is for a new line provide of FTTP on a new ONT via a managed install.
Request Method & URI
POST /hubco/tmf/productOrderingManagement/v4/productOrderRequest Entity-Body
We've split the request into distinct sections.
Section 1: Access technology and end user address/es
| Key | Value (example) | Notes | Source |
|---|---|---|---|
| externalId | 45671012MZNM-P-1697133014501 | Reference assigned by your business to this order. | Your systems |
| requestedCompletionDate | 2022-11-29T00:00:00Z | Based on any selected appointment date (Managed Install) or the standard lead times as given in the Broadband One Product Handbook. | Provisional until expected completion date provided by order update KSU. |
| productOrderItem.id | 100 | Order items are nested, comprising a root order item for the Broadband One access and nested items such as Managed Install. Here we've used 100, then 100.1, 100.2... for the nested items. | Your systems |
| productOrderItem.product.productOffering.id | E0000160 | Id for the product offering for the Broadband One access (ie FTTP, or SOGEA). | Mapping from product offer qualification API (productOfferingQualificationItem.product.productOffering.id) to product offering code in the product catalogue. |
| productOfferingQualificationItem.product.place.id | R09761999999 | The address keys for the premises. These are given in pairs; one from the Rest of BT database the other from the Openreach database. This "SiteAddress" key is the RoBT key. | API: GET List geographic address (or POST Create temporary ROBT address record, if no matchingId found). |
| productOfferingQualificationItem.product.place.id | A15104999999 | The address keys for the premises. These are given in pairs; one from the Rest of BT database the other from the Openreach database. The "OpenreachAddress" key is accompanied by the district code for a "gold" key from the Openreach database. | API: GET List geographic address |
Payload
{
"externalId": "45671012MZNM-P-1697133014501",
"requestedCompletionDate": "2022-11-29T00:00:00Z",
"productOrderItem": [
{
"id": "100",
"action": "add",
"product": {
"productOffering": {
"id": "E0000160"
},
"place": [
{
"id": "R09761999999",
"role": "SiteAddress",
"@type": "btRelatedPlaceRefOrValue"
},
{
"id": "A15104999999",
"role": "OpenreachAddress",
"address": {
"districtCode": "LS"
},
"@type": "btRelatedPlaceRefOrValue"
}
],
Section 2: Product characteristics
Inclusion of specific attributes (productCharacteristic) and their values is based on the requirements of the product offering and order type and informed by information from:
- Previous API responses
- The Product catalogue
- Ofcom (the RID code, known here as the ATT_RT_ResellerID value).
| Name | Value (example) | Source | Notes |
|---|---|---|---|
| ATT_RT_InstallType | M | Product catalogue | Managed Install (M) or Self Install (S) |
| ATT_RT_AccessTechnology | FTTP | Product catalogue | |
| ATT_X_JOURNEYTYPE | NewLineProvide | Product catalogue | |
| ATT_RT_ONTType | New ONT | API | |
| ATT_RT_ProductMinimumGuaranteedSpeed | 76 | API | Shown as productMinimumGuaranteedSpeed in the productCharacteristic array of the product offering qualification response. The minimum guaranteed speed should be communicated to the end customer at the time of sale. |
| ATT_RT_EndUserType | Residential | Product catalogue | |
| ATT_RT_TrafficWeighting | Standard | Product catalogue | |
| ATT_RT_ContractTerm | 12 | Product catalogue | Find out more in the Broadband One Product Handbook. |
| ATT_RT_ContractTermUnit | Month | Product catalogue | Find out more in the Broadband One Product Handbook. |
| ATT_RT_ResellerID | ZYX | Ofcom | Your three-character RID code. |
Payload
"productCharacteristic": [
{
"name": "ATT_RT_InstallType",
"value": "M"
},
{
"name": "ATT_RT_AccessTechnology",
"value": "FTTP"
},
{
"name": "ATT_X_JOURNEYTYPE",
"value": "NewLineProvide"
},
{
"name": "ATT_RT_ONTType",
"value": "New ONT"
},
{
"name": "ATT_RT_ProductMinimumGuaranteedSpeed",
"value": "76"
},
{
"name": "ATT_RT_EndUserType",
"value": "Residential"
},
{
"name": "ATT_RT_TrafficWeighting",
"value": "Standard"
},
{
"name": "ATT_RT_ContractTerm",
"value": "12"
},
{
"name": "ATT_RT_ContractTermUnit",
"value": "Month"
},
{
"name": "ATT_RT_ResellerID",
"value": "ZYX"
}
],
Section 3: Contact details, Managed Install appointment, and notes for the engineer
For provide orders at least one set of site contact details should be provided.
This should be included whether a Managed Install or Self Install, since it could be used by office or field-based Openreach or BT Wholesale staff.
The additionalNotes array contains information for visiting engineers .
| Key | Value (example) | Notes | Source |
|---|---|---|---|
| appointment.id | S987832 | Your own identifier for the appointment. Can be generated by your systems or the value provided in the response when you reserved the appointment (shown in this payload as BESAppointmentId) | Your systems |
| appointment.BESAppointmentId | A42D0BDFR | Appointment identifier provided in the response when you reserved the appointment | API (Appointment management) |
| appointment.appointmentStart | 2022-11-29T08:00:00Z | API (Appointment management) | |
| billingAccount.id | 0455821481 | Your BT Wholesale account number | Your systems |
| additionalNotes.text | Must be included when Managed Install required. Used to warn engineer of any hazards; if there are none, the array must still be included and the text values, as shown below, left blank. | Your systems |
Payload
"relatedParty": [
{
"id": "noneed",
"role": "PrimarySiteContact",
"familyName": "Reddy",
"givenName": "Saipriya",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"contactType": "PrimaryWork",
"emailAddress": "msaipriya.reddy@abc.com"
}
},
{
"mediumType": "telephone",
"characteristic": {
"contactType": "PrimaryWork",
"phoneNumber": "07700900099"
}
}
],
"@type": "BTRelatedParty",
"@referredType": "Individual"
}
],
"@type": "BTProductRefOrValue"
},
"appointment": {
"id": "S987832",
"BESAppointmentId": "A42D0BDFR",
"appointmentStart": "2022-11-29T08:00:00Z"
},
"billingAccount": {
"id": "0455821481"
},
"additionalNotes": [
{
"text": "",
"type": "Engineering",
"@type": "BTNote"
},
{
"text": "",
"type": "HazardNote",
"@type": "BTNote"
}
],
Section 4: Child products and attributes
These item structures will look familiar since they follow the root product model.
Each productOrderItem.product.productOffering.id value is the product offering id (shown in the product catalogue) for a child product for the Broadband One order.
| id | Code | Product | Notes |
|---|---|---|---|
| 100.1 | E0000027 | Enhanced Care | Fault repair response time. |
| 100.2 | E0000703 | Dynamic IP | Alternative is up to 6 static IPs. |
| 100.3 | E0000152 | Premium Managed Install | Assigns additional engineering time. Often ordered to provide customer with configuration support (such as rerouting of internal cabling). |
Premium Managed Install has additional attributes (as shown in the product catalogue).
| Property | Value (example) | Use | Notes |
|---|---|---|---|
| ATT_RT_ECCChargeband | 0 | Required (for FTTP) |
Indicates pre-authorised cost limits associated with any excess construction charges (ECCs) exceeding £1,000. ECC bands are 0 to 5, with 0 meaning you don't preauthorise any additional charges and they will require authorisation following receipt of an order update KSU. All ECC bands are shown in your Broadband One contract annexes. The benefit of preauthorising ECCs is in quickly and automatically progressing orders if additional infrastructure beyond Openreach's commercial network build is required. One ECC example - though there are several other scenarios - is if your customer wants the ONT sited some distance away from where Openreach would normally install it. You would always be notified by KSU of ECCs - but not expected to respond with authorisation if the charges are within the limit defined by this value. |
| ATT_RT_SiteVisitReason | Premium | Required | Confirms Premium Managed Install. |
| ATT_RT_FTTPInstallType | 1 Stage | Required (for FTTP) | Whether the install is likely to require one, or two (KCI2 Assure) visits. |
Payload
"productOrderItem": [
{
"id": "100.1",
"action": "add",
"product": {
"productOffering": {
"id": "E0000027"
},
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
},
{
"id": "100.2",
"action": "add",
"product": {
"productOffering": {
"id": "E0000703"
},
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
},
{
"id": "100.3",
"action": "add",
"product": {
"productOffering": {
"id": "E0000152"
},
"productCharacteristic": [
{
"name": "ATT_RT_ECCChargeband",
"value": "0"
},
{
"name": "ATT_RT_SiteVisitReason",
"value": "Premium"
},
{
"name": "ATT_RT_FTTPInstallType",
"value": "1 Stage"
}
],
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
}
],
"@type": "BTProductOrderItem"
}
],
Section 5: Your business and customer information
The request ends with your:
- BT Wholesale CUG (shown in your account)
- End Customer’s ID (An ID for the party the service has been sold to.)
- Reseller's contact information
Good to know: These details are associated with the order as a whole - not any specific products within it.
Payload
"relatedParty": [
{
"id": "CUG5009999999",
"role": "BtCug",
"@type": "BTRelatedParty",
"@referredType": "Customer"
},
{
"id": "0003086103",
"role": "EndCustomer",
"@type": "BTRelatedParty",
"@referredType": "Customer"
},
{
"id": "AdditionalEmail1",
"role": "PrimaryOrderContact",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"contactType": "PrimaryWork",
"emailAddress": "msaipriya.reddy@xyz.com"
}
}
],
"@referredType": "Individual",
"@type": "BTRelatedParty"
},
{
"id": "AdditionalEmail2",
"role": "SecondaryOrderContact",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"contactType": "PrimaryWork",
"emailAddress": "msaipriya.reddy@xyz.com"
}
}
],
"@type": "BTRelatedParty",
"@referredType": "Individual"
}
],
"@type": "BTProductOrder"
}
Response
You’ll receive a HTTP 202 OK response to indicate the order is queued for processing. If there is an issue with the request a 40x or 50x response will be returned with an error message. Subsequently to that a product order create event will be returned indicating success or failure in creating the order in our CRM platform. After successful creation of the order there will follow a series of product order state change event notifications showing order progress.
Error codes and their meanings are shown in the reference documentation.
Modify
This order type allows a provider to change aspects of a provided product and supports changes to the chosen product offerings and product attributes.
Changing the chosen root product offering means changing the access technology (product family migration/PFM), and/or speed (known as a regrade when the access technology stays the same).
Product attribute/s (such as traffic weighting – from standard to elevated) can be changed with or without the change of the product offering.
Similarly changes can be made to the chosen child product offerings (care level and dynamic/static IP).
When changing the root product offering (PFM or regrade) the modify order must identify the relationship of the order to the existing provided product using ProductRelationship (with a relationshipType key-value pair of changeTechnology for PFM, and changeOffer for regrade). ProductRelationship is not required when solely changing product characteristics or child products and not changing the root product offering.
We've included several examples of Modify order requests below. Code snippets show the tree representation of the JSON order structure and relationships between objects and arrays. In summary the examples illustrate the following.
| Root product | Child product | What's changing? |
|---|---|---|
| Y | N | Access technology (product family migration) |
| Y | N | Speed (regrade) |
| Y | N | Traffic weighting - standard to elevated |
| Y | Y | Modify child products while modifying root product |
| N | Y | Standard to Enhanced Care |
Modify access technology (product family migration)
Migration from FTTC to FTTP
- action: modify
- relationshipType: changeTechnology
Since this order requires a new ONT, a Managed Install and appointment must also be requested.
Many new product characteristics will also be required in this request. Those attributes are shown in the product catalogue, and Provide tutorial.
Request Entity-Body
| Property | Value (example) | Notes |
|---|---|---|
| productOrderItem.id | 200 | Number of your choice identifying this item |
| productOrderItem.action | modify | This is a ‘modify’ action because you are replacing one access product offering with another for an existing installed product. |
| productOrderItem.product.id | Asset ID shown in KSUs when original access technology was ordered. | |
| productOrderItem.product.productOffering.id | E0000021 | Product code for requested access technology and speed. |
| productOrderItem.product.productRelationship.relationshipType | changeTechnology | Required for a change of access technology (product family migration). |
| productOrderItem.product.productRelationship.product.id | Asset ID shown in KSUs when original access technology was ordered. | |
| productOrderItem.appointment | This object would include details about an engineering visit reserved with the appointing API. | |
| productOrderItem.productOrderItem | Child product requesting the provision of a Managed Install (ecode E0000153). |
Payload
{
"externalId": "Modify Product Familiy Migration FTTC to FTTP",
"requestedCompletionDate": "2022-11-25T00:00:00Z",
"productOrderItem": [
{
"id": "200",
"action": "modify",
"product": {
"id": "472270c9-46cb-4d3f-8e39-46c7093ccccc",
"productOffering": {
"id": "E0000021"
},
"productCharacteristic": [
{
"name": "ATT_RT_AccessTechnology",
"value": "FTTP",
"@type": "BTCharacteristic"
},
{
"name": "ATT_X_JOURNEYTYPE",
"value": "Migration"
},
{
"name": "ATT_RT_MigrationReason",
"value": "FTTPMigration"
},
{
"name": "ATT_RT_ONTType",
"value": "New ONT",
"@type": "BTCharacteristic"
},
{
"name": "ATT_RT_InstallType",
"value": "M",
"@type": "BTCharacteristic"
},
{
"name": "ATT_RT_ProductMinimumGuaranteedSpeed",
"value": "70",
"@type": "BTCharacteristic"
},
{
"name": "ATT_RT_ContractTerm",
"value": "12",
"@type": "BTCharacteristic"
},
{
"name": "ATT_RT_ContractTermUnit",
"value": "Month",
"@type": "BTCharacteristic"
}
],
"productRelationship": [
{
"relationshipType": "changeTechnology",
"product": {
"id": "472270c9-46cb-4d3f-8e39-46c7093ccccc"
}
}
],
"place": [
{
"id": "R00000521994",
"role": "SiteAddress",
"@type": "btRelatedPlaceRefOrValue"
},
{
"id": "A99923776374",
"role": "OpenreachAddress",
"address": {
"districtCode": "LS"
},
"@type": "btRelatedPlaceRefOrValue"
}
],
"relatedParty": [
{
"id": "-1",
"role": "PrimarySiteContact",
"familyName": "Pranjali",
"givenName": "TawareSite",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"contactType": "Primary Work",
"emailAddress": "ptemailsite@gmail.com"
}
},
{
"mediumType": "telephone",
"characteristic": {
"contactType": "Primary Work",
"phoneNumber": "0123451243"
}
}
],
"@type": "BTRelatedParty",
"@referredType": "Individual"
}
],
"@type": "BTProductRefOrValue"
},
"appointment": {
"id": "1",
"appointmentStart": "2022-11-25T08:00:00Z",
"BESAppointmentId": "A57C0BDFR"
},
"productOrderItem": [
{
"id": "200.1",
"action": "add",
"product": {
"productOffering": {
"id": "E0000153"
},
"productCharacteristic": [
{
"name": "ATT_RT_ECCChargeband",
"value": "0"
},
{
"name": "ATT_RT_FTTPInstallType",
"value": "1 Stage",
"@type": "BTCharacteristic"
},
{
"name": "ATT_RT_SiteVisitReason",
"value": "Premium",
"@type": "BTCharacteristic"
}
],
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
}
],
"@type": "BTProductOrderItem"
}
],
"relatedParty": [
{
"id": "CUG5002237010",
"role": "BtCug",
"@type": "BTRelatedParty",
"@referredType": "Customer"
},
{
"id": "-1",
"role": "PrimaryOrderContact",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"emailAddress": "ptemail1@gmail.com",
"contactType": "Primary Work"
}
}
],
"@type": "BTRelatedParty",
"@referredType": "Individual"
},
{
"id": "-2",
"role": "SecondaryOrderContact",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"emailAddress": "ptemail2@gmail.com",
"contactType": "Primary Work"
}
}
],
"@type": "BTRelatedParty",
"@referredType": "Individual"
}
],
"@type": "BTProductOrder"
}Modify speed (regrade)
Regrading to FTTC 80_20M
- action: modify
- relationshipType: changeOffer
The new product features a minimum guaranteed access line speed of 62 Mbps.
Request Entity-Body
| Property | Value (example) | Notes |
|---|---|---|
| productOrderItem.id | 200 | Number of your choice identifying this item |
| productOrderItem.action | modify | This is a ‘modify’ action because you are replacing one access product offering with another for an existing installed product (albeit just a different speed within the same technology). |
| productOrderItem.product.id | Asset ID shown in KSUs when original access technology was ordered. | |
| productOrderItem.product.productOffering.id | E0000529 | Product offering code for requested access technology and speed. |
| productOrderItem.product.productCharacteristic.name | ATT_RT_ProductMinimumGuaranteedSpeed | Minimum guaranteed access line speed, key. |
| productOrderItem.product.productCharacteristic.value | 62 | Minimum guaranteed speed. Shown in product offer response. Must be included in customer contract. |
| productOrderItem.product.productRelationship.relationshipType | changeOffer | Required for a regrade request. |
| productOrderItem.product.productRelationship.product.id | Asset ID shown in KSUs when original access technology was ordered. |
Payload
{
"externalId": "Modify Change Speed",
"requestedCompletionDate": "2022-11-25T00:00:00Z",
"productOrderItem": [
{
"id": "200",
"action": "modify",
"product": {
"id": "d90936db-a191-4c65-a4bb-a1cc67b04fff",
"productOffering": {
"id": "E0000529"
},
"productCharacteristic": [
{
"name": "ATT_RT_ProductMinimumGuaranteedSpeed",
"value": "62",
"@type": "BTCharacteristic"
}
],
"productRelationship": [
{
"relationshipType": "changeOffer",
"product": {
"id": "d90936db-a191-4c65-a4bb-a1cc67b04fff"
}
}
],
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
}
],
"relatedParty": [
{
"id": "CUG5009999999",
"role": "BtCug",
"@type": "BTRelatedParty",
"@referredType": "Customer"
},
{
"id": "-1",
"role": "PrimaryOrderContact",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"emailAddress": "ptemail1@gmail.com",
"contactType": "Primary Work"
}
}
],
"@type": "BTRelatedParty",
"@referredType": "Individual"
},
{
"id": "-2",
"role": "SecondaryOrderContact",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"emailAddress": "ptemail2@gmail.com",
"contactType": "Primary Work"
}
}
],
"@type": "BTRelatedParty",
"@referredType": "Individual"
}
],
"@type": "BTProductOrder"
}Modify root product attribute
Changing traffic weighting from Standard to Elevated
action: modify
The customer requires enhanced traffic weighting, a root product attribute .
There are several root product attributes. In a modify order one only needs to mention the ones which are changing with their new values.
While changing the root product attributes one might also wish to add or remove child products (described further below).
Request Entity-Body
| Property | Value (example) | Notes |
|---|---|---|
| id | 100 | Numerical value of your choice. |
| action | modify | When you change one of its attributes, the root product is being modified. |
| name | ATT_RT_TrafficWeighting | Attribute as shown in the product catalogue. |
| value | Elevated | This is the requested change. You don't need to include the old value - there is only one active value per attribute. |
Payload
{
"externalId": "Modify Traffic Weighting Dynamic IP and Standard Care",
"requestedCompletionDate": "2022-11-25T00:00:00Z",
"productOrderItem": [
{
"id": "100",
"action": "modify",
"product": {
"id": "472270c9-46cb-4d3f-8e39-46c7093ff024",
"productOffering": {
"id": "E0000021"
},
"productCharacteristic": [
{
"name": "ATT_RT_TrafficWeighting",
"value": "Elevated",
"@type": "BTCharacteristic"
}
],
"@type": "BTProductRefOrValue"
},
"productOrderItem": [
{
"id": "100.1",
"action": "delete",
"product": {
"id": "d90936db-a191-4c65-a4bb-a1cc67b0400f",
"productOffering": {
"id": "E0000028"
},
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
},
{
"id": "100.2",
"action": "add",
"product": {
"productOffering": {
"id": "E0000027"
},
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
},
{
"id": "100.3",
"action": "delete",
"product": {
"id": "a7a5352d-3905-43c7-9def-15cb6789e92f",
"productOffering": {
"id": "E0000703"
},
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
},
{
"id": "100.4",
"action": "add",
"product": {
"productOffering": {
"id": "E0000701"
},
"productCharacteristic": [
{
"name": "ATT_DT_NoofIPs",
"value": "6",
"@type": "BTCharacteristic"
}
],
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
}
],
"@type": "BTProductOrderItem"
}
],
"relatedParty": [
{
"id": "CUG5009999999",
"role": "BtCug",
"@type": "BTRelatedParty",
"@referredType": "Customer"
},
{
"id": "-1",
"role": "PrimaryOrderContact",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"emailAddress": "ptemail1@gmail.com",
"contactType": "Primary Work"
}
}
],
"@referredType": "Individual",
"@type": "BTRelatedParty"
},
{
"id": "-2",
"role": "SecondaryOrderContact",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"emailAddress": "ptemail2@gmail.com",
"contactType": "Primary Work"
}
}
],
"@referredType": "Individual",
"@type": "BTRelatedParty"
}
],
"@type": "BTProductOrder"
}
Modify root and child products
Standard Care with Enhanced Care; Dynamic IP with 6 Static IPs
- action: add and delete
Child products can be modified whether or not the root product is is being changed.
The same order above includes changes to child products.
Request Entity-Body
| Property | Value (example) | Notes |
|---|---|---|
| id | 100.1 | Child product of the 100-labelled root. |
| action | delete | We're removing Standard Care. |
| productOffering.id | E0000028 | Ecode for Standard Care. |
| id | 100.2 | Your numerical label for the Enhanced Care product order. |
| action | add | We're adding Enhanced Care. |
| productOffering.id | E0000027 | Product offering code for Enhanced Care. |
| id | 100.3 | Your numerical label for removing Dynamic IP. |
| action | delete | We're removing Dynamic IP. |
| productOffering.id | E0000703 | Product offering coded for Dynamic IP. |
| id | 100.4 | Your numerical label for the Static IP product order. |
| action | Add | We're adding Static IP. |
| productOffering.id | E0000701 | Product offering code for Static IP. |
| productCharacteristic.name | ATT_DT_NoofIPs | Static IP attribute key. |
| productCharacteristic.value | 6 | Number of static IPs. |
Payload
Shown above.
Modify child product only
Replacing Standard Care with Enhanced Care
- action: noChange (for access technology)
- action: delete (product being replaced)
- action: add (replacement product)
The root product must always be included. When it’s not being modified (access technology/speed/attribute), it must have an associated action of noChange.
Request Entity-Body
| Property | Value (example) | Notes |
|---|---|---|
| productOrderItem.id | 100 | Number of your choice identifying this item |
| productOrderItem.action | noChange | While the access technology is unchanged, it still needs to be included in the request - with this action value. |
| productOrderItem.product.id | Asset ID shown in KSUs when original access technology was ordered. | |
| productOrderItem.product.productOffering.id | E0000021 | Product code for the existing access product which is not changing (FTTP 80_20M). |
| productOrderItem.productOrderItem.id | 100.1 | Indicates this is a child product of the root, which here is 100. Values can be anything, and defined by you. |
| productOrderItem.productOrderItem.action | delete | Request for product removal - here, Standard Care. |
| productOrderItem.productOrderItem.product.id | * | This is the Asset ID of the original care level product as indicated in KSUs following receipt of the original Standard Care order |
| productOrderItem.productOrderItem.product.productOffering.id | E0000028 | Standard Care. |
| productOrderItem.productOrderItem.id | 100.2 | Numerical label for the replacement product. |
| productOrderItem.productOrderItem.action | add | Request for new product - here, Enhanced Care. |
| productOrderItem.productOrderItem.product.productOffering.id | E0000027 | Product offer code for Enhanced Care. |
Payload
{
"externalId": "Modify Standard to Enhanced Care",
"requestedCompletionDate": "2022-11-25T00:00:00Z",
"productOrderItem": [
{
"id": "100",
"action": "noChange",
"product": {
"id": "8f59edae-fb5c-4438-a402-f2c7f8d4b802",
"productOffering": {
"id": "E0000021"
},
"@type": "BTProductRefOrValue"
},
"productOrderItem": [
{
"id": "100.1",
"action": "delete",
"product": {
"id": "a8a55e86-b81d-436f-aab7-998de4ade3d1",
"productOffering": {
"id": "E0000028"
},
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
},
{
"id": "100.2",
"action": "add",
"product": {
"productOffering": {
"id": "E0000027"
},
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
}
],
"@type": "BTProductOrderItem"
}
],
"relatedParty": [
{
"id": "CUG5009999999",
"role": "BtCug",
"@type": "BTRelatedParty",
"@referredType": "Customer"
},
{
"id": "-1",
"role": "PrimaryOrderContact",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"emailAddress": "ptemail1@gmail.com",
"contactType": "Primary Work"
}
}
],
"@referredType": "Individual",
"@type": "BTRelatedParty"
},
{
"id": "-2",
"role": "SecondaryOrderContact",
"contactMedium": [
{
"mediumType": "email",
"characteristic": {
"emailAddress": "ptemail2@gmail.com",
"contactType": "Primary Work"
}
}
],
"@referredType": "Individual",
"@type": "BTRelatedParty"
}
],
"@type": "BTProductOrder"
}
Response
You’ll receive a HTTP 202 OK response indicate an order queued for processing. Otherwise a 40x or 50x response is given with an error message.
The subsequent KSUs will depend on the nature of what is being changed. For example if there is no change to the broadband access or its associated care level there will not be any BTWholesale/Openreach associated codes like 510/520/530 etc.
Cease
Request Entity-Body
To cease an active Broadband One product, use the action of delete against the root product.
Include the asset ID (not the Broadband One customer facing service ID) shared in KSUs following receipt of the original order request.
Payload
{
"externalId": "Broadband One Cease",
"requestedCompletionDate": "2022-12-20T00:00:00Z",
"productOrderItem": [{
"id": "100",
"action": "delete",
"product": {
"id": "7682204c-c580-b2d6-80ed-370e0827a583",
"productOffering": {
"id": "E0000021"
},
"@type": "BTProductRefOrValue"
},
"note": {
"text": "Price Issue",
"type": "CessationInstruction",
"@type": "BTNote"
},
"@type": "BTProductOrderItem"
}],
"relatedParty": [{
"id": "CUG5009999999",
"role": "BtCug",
"@type": "BTRelatedParty",
"@referredType": "Customer"
},
{
"id": "-1",
"role": "PrimaryOrderContact",
"contactMedium": [{
"mediumType": "email",
"characteristic": {
"emailAddress": "ptemail1@xyz.com",
"contactType": "Primary Work"
}
}],
"@type": "BTRelatedParty",
"@referredType": "Individual"
},
{
"id": "-2",
"role": "SecondaryOrderContact",
"contactMedium": [{
"mediumType": "email",
"characteristic": {
"emailAddress": "ptemail2@xyz.com",
"contactType": "Primary Work"
}
}],
"@type": "BTRelatedParty",
"@referredType": "Individual"
}
],
"@type": "BTProductOrder"
}Valid cessation reasons (CessationInstruction)
The valid reasons which can be given when placing an order to cease a product are
- Mover retaining service
- Other
- Failure to Pay : Bad Debt
- Service Issue
- Price Issue
- Process Issue
- No Longer Required - No Change of CP
- Mis-Sold
- Data Integrity/Records only
- Downsizing
- Competitor Loss
- Bad Debt/Fair Usage
- Product: Below minimum guaranteed Broadband speed
There are additional reasons which just apply for SoGEA
- Move with Change of CP
- Change of CP
- Product Issue
Response
A positive synchronous response will be returned, followed by asynchronous events (KSUs) informing progress of the cease request.
Once the Broadband One product is ceased, all child products will also be ceased.
Amend
Amend part of an order using the PATCH method to a uri referencing the order resource by its id.
KSUs will advise on whether the order has been amended.
Request Method & URI
PATCH /hubco/tmf/productOrderingManagement/v4/productOrder/{id}Request Entity-Body
internalId is the product order item internalId from KSUs associated with the original Broadband One order request.
Restrictions
Not every aspect of the order can be amended - including selected product offerings, and most of the product characteristics.
Amend use cases
- Changing the requested completion date with any related appointment
- Adding notes
- Changing the characteristics of a managed install which give pre-approval for additional charges
- Changing contact details.
Dates, appointments, and notes
- Dates or appointments will replace those provided in the original order.
- Notes will be added to those already provided.
Payload
{
"requestedCompletionDate": "2022-12-22T00:00:00Z",
"productOrderItem": [
{
"id": "100",
"internalId": "00012233",
"action": "add",
"product": {
"productOffering": {
"id": "E0000186"
},
"@type": "BTProductRefOrValue"
},
"appointment": {
"id": "A42D0BDFR",
"appointmentStart": "2022-12-14T08:00:00Z",
"BESAppointmentId": "A42D0BDFR"
},
"note": {
"text": "This is hazard note",
"type": "HazardNote",
"@type": "BTNote"
},
"productOrderItem": [
{
"id": "100.3",
"internalId": "0003479233",
"action": "add",
"product": {
"productOffering": {
"id": "E0000152"
},
"productCharacteristic": [
{
"name": "ATT_RT_ECCChargeband",
"value": "4"
}
],
"@type": "BTProductRefOrValue"
},
"@type": "BTProductOrderItem"
}
],
"@type": "BTProductOrderItem"
}
],
"relatedParty": [
{
"id": "CUG5009999999",
"role": "BtCug",
"@type": "BTRelatedParty",
"@referredType": "Customer"
}
],
"@type": "BTProductOrder"
}Response
Acceptance of an amend request is determined by a combination of factors, including when they are received in the order process.
If your request is approved, a new ProductOrderCreateEvent KSU will be sent, followed by a chain of product order state change events. Although the order id will not change on amendment the internalIds of the product order items will change with revision of the order.
Cancel
Ask for the cancellation of an order in progress.
Cancellation of an order is requested by creating a cancelProductOrder task resource. This task is evaluated and if created the cancellation will be attempted. If it is felt that the cancellation will be unsuccessful the task resource will be rejected.
Subsequent KSUs will advise on whether the order has been cancelled.
Request Method & URI
POST /hubco/tmf/productOrderingManagement/v4/cancelOrderRequest Entity-Body
Cancellation is only possible if the Broadband One order is in a 'cancellable' state, as determined by its progress.
Each order is different; we'll advise whether cancellation is possible once a cancellation request has been received.
The payload object must include a cancellation reason.
Valid cancellation reasons (cancellationReason)
- Additional charge not accepted
- Unwilling to supply reason
- Delivery too long
- Chosen different supplier
- Placed in error / duplicate
- Price
- Insufficient lead time
Payload
{
"cancellationReason": "Placed in error / duplicate",
"productOrder": {
"id": "O-20211120210"
},
"@type": "CancelProductOrder_Create"
}productOrder.id is the BT Wholesale reference for the order to be cancelled.
Response
If a request to cancel an order looks acceptable, a synchronous response confirms receipt.
- Asynchronously a cancel task is more fully evaluated and created or rejected (and a positive or negative event is asynchronously returned - CancelProductOrderCreateEvent )
- If a cancellation looks viable a cancellation request will be placed with suppliers
- KSUs will be sent reporting the final outcome of the request.
Order updates (KSUs)
After order creation, a series of events are sent containing information about product order item status and any issues arising during fulfilment. These events also contain BT ids of product orders and product order items as well as the identities of products created. Occasionally these events contain "response codes" from downstream suppliers. The events are driven by the fulfilment process for each of the Broadband One products including the broadband access product which is delivered by BTWholesale/Openreach (WBMC End User Access).
Broadband One and Wholesale Broadband Connect (WBC)
Broadband One is a managed internet access product , with layer 2 access connectivity provided using the Wholesale Broadband Managed Connect (WBMC) product.
When a Broadband One provide order is placed, a WBC End User Access order is placed to provide the layer 2 access to the end user.
Notifications relating to WBC KCI (keep customer information) responses are forwarded via Broadband One KSUs and include the relevant Wholesale/Openreach response codes as a subCode and Message within the errorMessage object (although these are often not related to errors).
KSUs related to other Broadband One product fulfilment do not include subCode values of their own but may carry over WBMC codes from previous KSUs.
Common WBC (Layer 2) KSUs
The majority of order updates for WBMC End User Access provision are addressed by the messages and subCode values shown below. A word of warning. Often there are multiple such codes and messages sent in one event. Where this is the case the codes and messages are concatenated in the message attribute. When this happens the most "significant" code is used for the subCode. Therefore if there are warnings about changed appointments or dates at the time of the WBMC order commitment the subcode 520 (as an example) might be replaced by some other code. In that case the "usual" subcode will still be in the message with the other codes.
Download the complete list of response codes and notification messages (BTWholesale.com login required; this PDF document is located in the 'Lead To Cash (L2C) error and response codes' section).
| subCode | Message | Meaning |
|---|---|---|
| 510 | Order acknowledged and we aim to activate it as soon as possible. | The WBC order has passed initial validation and is ready to be sent to Openreach. |
| 520 | Order will be delivered as soon as possible. | The WBC order is now a committed order. |
| 530 | Order complete | The WBC order is now complete. |
| 540 | Amend request actioned | The WBC order has been amended. |
| 550 | Ad hoc note to CP | Note to the reseller. |
| 100101-100999 |
Order cancellation |
|
| 103001-103999 |
Amend request unsuccessful |
|
|
101001-101999 |
Delay notification | |
| 200000-200999 | Informational | |
Product Order Item State and Substatus
Individual product order items have a state and substatus. The state shows whether an item is open, complete or cancelled plus some other states. The substatus relates to the specific process that product order item undergoes during fulfilment.
The state and subStatus value combinations for the Broadband One product items for all provide journey types types are given in the table below.
| state | subStatus |
|---|---|
| assessingCancellation | AcceptedByBTWwBC |
| assessingCancellation | Cancellation Request |
| assessingCancellation | CancellationAccepted |
| assessingCancellation | CancelledBTWwBCService |
| assessingCancellation | CommittedByBTWwBC |
| assessingCancellation | FlaggedForAttention |
| cancelled | Cancelled |
| cancelled | CancelledBTWwBCService |
| completed | Closed |
| completed | CompletedBTWwBCService |
| completed | NoFulfillment |
| failed | Failed |
| failed | FailedBTWwBCService |
| inProgress | AcceptedByBTWwBC |
| inProgress | Amend Request |
| inProgress | AmendedByBTWwBC |
| inProgress | AmendmentAccepted |
| inProgress | AmendmentRejected |
| inProgress | AwaitingECCConfirmation |
| inProgress | CancelledBTWwBCService |
| inProgress | CommittedByBTWwBC |
| inProgress | CompletedBTWwBCService |
| inProgress | DelayedBySupplier |
| inProgress | DisconnectEsideCopperByBTWwbc |
| inProgress | ECCApply |
| inProgress | ECCReminder |
| inProgress | FailedBTWwBCService |
| inProgress | FlaggedForAttention |
| inProgress | In Progress |
| inProgress | inProgress |
| inProgress | PendingWithBTWwBC |
| rejected | AmendmentRejected |
KSU examples
This KSU informs that the request has been received and the order is now in progress.
event.productOrder.productOrderItem.product.id (here, starting 3447) is the asset ID required in a request to modify or cease a product. Similarly Product ids for the child products will need to be retained for subsequent modification or removal/replacement.
Care should also be given to looking at the product ids on modification of a product and its children as for certain scenarios new product ids will be allocated.
{
"event": {
"productOrder": {
"errorMessage": [],
"externalId": "622FTTPNEWONTpreprod",
"id": "00228874",
"productOrderItem": [
{
"id": "100",
"internalId": "0004130371",
"action": "add",
"state": "inProgress",
"subStatus": "In Progress",
"product": {
"productOffering": {
"id": "E0000189"
},
"@type": "BTProductRefOrValue",
"customerFacingServiceId": {
"value": "BBONE0005347",
"previousValue": ""
},
"id": "3447fc9b-ba5b-3520-3751-cc4239a8b2c0",
"productCharacteristic": []
},
"@type": "BTProductOrderItem"
}
],
"relatedParty": [
{
"@referredType": "Customer",
"@type": "BTRelatedParty",
"role": "BtCug",
"id": "CUG5009999999"
}
],
"@type": "BTProductOrder"
}
},
"eventType": "ProductOrderStateChangeEvent",
"eventTime": "2023-02-13T09:21:07.976Z",
"eventId": "f9616bf1-4e23-9de3-fe62-1243aa92a92a"
}510
As mentioned in the table above, this subCode value refers to the order being validated by BT Wholesale and it now being passed to Openreach for WBC provisioning.
{
"event": {
"productOrder": {
"externalId": "622FTTPNEWONTpreprod",
"id": "00228874",
"errorMessage": [
{
"subCode": "510",
"message": "Informational : 510 : Order Acknowledge",
"productOrderItem": [
{
"itemId": "100"
}
]
},
{
"subCode": "510",
"message": "Informational : 510 : Order Acknowledge",
"productOrderItem": [
{
"itemId": "100.1"
}
]
}
],
"productOrderItem": [
{
"id": "100",
"internalId": "0004130371",
"action": "add",
"state": "inProgress",
"subStatus": "AcceptedByBTWwBC",
"product": {
"productOffering": {
"id": "E0000189"
},
"@type": "BTProductRefOrValue",
"customerFacingServiceId": {
"value": "BBONE0005347",
"previousValue": ""
},
"id": "3447fc9b-ba5b-3520-3751-cc4239a8b2c0",
"productCharacteristic": []
},
"@type": "BTProductOrderItem"
},
{
"id": "100.1",
"internalId": "0004130376",
"action": "add",
"state": "inProgress",
"subStatus": "AcceptedByBTWwBC",
"product": {
"productOffering": {
"id": "E0000027"
},
"@type": "BTProductRefOrValue",
"customerFacingServiceId": {
"value": "BBONE0005347",
"previousValue": ""
},
"id": "ff7aac03-be9f-e83d-b991-1c1207537662",
"productCharacteristic": []
},
"@type": "BTProductOrderItem"
},
{
"id": "100.2",
"internalId": "0004130380",
"action": "add",
"state": "completed",
"subStatus": "Closed",
"product": {
"productOffering": {
"id": "E0000703"
},
"@type": "BTProductRefOrValue",
"customerFacingServiceId": {
"value": "BBONE0005347",
"previousValue": ""
},
"id": "9e4ba9d3-2bd9-6ae8-a327-211dd7f65323",
"productCharacteristic": []
},
"@type": "BTProductOrderItem"
}
],
"relatedParty": [
{
"@referredType": "Customer",
"@type": "BTRelatedParty",
"role": "BtCug",
"id": "CUG5009999999"
}
],
"@type": "BTProductOrder"
}
},
"eventType": "ProductOrderStateChangeEvent",
"eventTime": "2023-02-13T09:53:19.019Z",
"eventId": "d4c0a7d5-7844-5f46-b1b2-12422925de28"
}520
At this stage, the WBC element of the order is committed. The rest of the payload is the same as shown above (510).
{
"event": {
"productOrder": {
"externalId": "622FTTPNEWONTpreprod",
"id": "00228874",
"errorMessage": [
{
"subCode": "520",
"message": "Informational : 520 : Order Committed",
"productOrderItem": [
{
"itemId": "100"
}
]
},
{
"subCode": "520",
"message": "Informational : 520 : Order Committed",
"productOrderItem": [
{
"itemId": "100.1"
}
]
}
],530
This KSU indicates the order is complete. The rest of the payload is the same as shown above (510).
{
"event": {
"productOrder": {
"externalId": "622FTTPNEWONTpreprod",
"id": "00228874",
"errorMessage": [
{
"subCode": "530",
"message": "Informational : 530 : Order Complete",
"productOrderItem": [
{
"itemId": "100"
}
]
},
{
"subCode": "530",
"message": "Informational : 530 : Order Complete",
"productOrderItem": [
{
"itemId": "100.1"
}
]
}
],Appointments
Some Broadband One orders require Openreach technicians to visit an end user's premises to install or configure equipment. For these visits, appointments can be reserved and included in submitted orders.
Occasionally, Openreach will change appointment dates, allocate an appointment of their own where there previously was not one or even cancel reserved appointments as not being required.
To keep reseller's and end users aware of appointment details these are shared in the product order state change events. On most occasions this information will be about the appointment made prior to placing the order and will just confirm the appointment status. On other occasions however this information will include specifics of changed dates, cancelled appointments or newly booked ones. The snippet below shows what appointment information looks like in a product order state change event.
{
"id": "100",
"internalId": "0003979076",
"action": "add",
"state": "inProgress",
"subStatus": "CommittedByBTWwBC",
"product": {
"productOffering": {
"id": "E0000186"
},
"@type": "BTProductRefOrValue",
"customerFacingServiceId": {
"value": "BBONE0026467",
"previousValue": ""
},
"id": "95cd2484-104c-1661-3a8f-f8be0673501c",
"productCharacteristic": [
{
"name": "ATT_RT_ONTReferenceNumber",
"value": "ONT0046482937",
"@type": "BTCharacteristic"
}
]
},
"@type": "BTProductOrderItem",
"expectedCompletionDate": "2023-11-21T08:43:50.000Z",
"appointment": {
"id": "S987321",
"BESAppointmentId": "A42D0BDFR",
"appointmentStatus": "Confirmed",
"appointmentStart": "2023-11-21T08:00:00.000Z",
"appointmentFinish": "2023-11-21T13:00:00.000Z"
}
},The id will be the id allocated by the reseller placing the order unless the appointment has been added by Openreach in which case it will be a BT allocated id.
appointmentStatus is typically one of the values given in the table below.
|
Appointment Status |
|---|
| Booked |
| Confirmed |
| Closed |
| Cancelled |
| AtRisk |
| SupplierChanged |
| CustomerMissed |
| SupplierMissed |
Other Broadband One tutorials
There are tutorials for every API leading to, and including, placing the order:
Additional support
- Broadband One Product Handbook (BT Wholesale login required)
- Reference documentation
- Product catalogue
- Knowledge centre