Skip to main content

Order Management And Progress Updates

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 productA "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:

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.

Explore end to end Broadband One order process by API

Prerequisites

Every API request requires an OAuth 2 bearer token.

First time working with our APIs?

  1. Register on this developer portal
  2. Create a Broadband One app for a Consumer Key and Consumer Secret
  3. Read the OAuth 2 reference documentation to generate your bearer token.

Explore payload examples

Run in Postman

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. 

Download the payload.

Request Method & URI

POST /hubco/tmf/productOrderingManagement/v4/productOrder

Request Entity-Body

We've split the request into distinct sections.

Section 1: Access technology and end user address/es

 
Property 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 .

Property 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.

One can move network termination equipment (NTE)  or  an optical network terminal (ONT) by placing a modify order with an appoinment and adding a specific managed install product/ site visit reason for "Shift NTE" or "Shift ONT"

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
N Y Shift ONT

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"
                        }
                    }
                ],
                "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"
}

Modify Shift ONT

  • action: noChange (for access technology)
  • action: add (Shift ONT managed install product)

The root product is included with the managed/self install attribute set to M. However since this is not changing the assetted characteristics of the access product the action is still noChange.

Request Entity-Body

Property Value (example) Notes
productOrderItem.action noChange The access product is not being changed.

productOrderItem.product.

productCharacteristic.name

ATT_RT_InstallType The value is set to M as this is a managed install.

productOrderItem.product.

relatedParty

  Site contact details are required as this is a managed install.

productOrderItem.

appointment

  An appointment is required as this is a managed install.

productOrderItem.

productOrderItem.action

add A child managed install product for Shift ONT is added.

productOrderItem.

productOrderItem.product.

productOffering.id

V0000030 This is the product offering id for  Managed Install Shift ONT.
Payload
{
    "externalId": "FTTP Modify Shift ONT",
    "requestedCompletionDate": "2024-08-21T00:00:00Z",
    "productOrderItem": [
        {
            "id": "100",
            "action": "noChange",
            "product": {
                "id": "d90936db-a191-4c65-a4bb-a1cc67b04fff",
                "productOffering": {"id": "E0000021"},
                "productCharacteristic": [
                    {"name": "ATT_RT_InstallType", "value": "M"}
                ],
                "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": "01632446657"
                                }
                            }
                        ],
                        "@type": "BTRelatedParty",
                        "@referredType": "Individual"
                    }
                ],
                "@type": "BTProductRefOrValue"
            },
            "appointment": {
                "id"              : "1"                   ,
                "appointmentStart": "2024-08-21T00:00:00Z",
                "BESAppointmentId": "383BRNWM"
            },
            "additionalNotes": [
                {"text": "Access to premises is via side gate.",
                "type": "Engineering","@type": "BTNote"},
                {"text": "Drop wire comes into premises over fragile flat roof.", 
                "type": "HazardNote","@type": "BTNote"}
            ],
            "productOrderItem": [
                {
                    "id": "100.1",
                    "action": "add",
                    "product": {
                        "productOffering": {"id": "V0000030"},
                        "productCharacteristic": [
                            {"name" : "ATT_RT_SiteVisitReason","value": "Shift ONT"
                            },
                            {"name": "NTEFloor","value": "1st"},
                            {"name": "NTERoom","value": "Study"},
                            {"name": "Position","value": "Right Hand side wall"}
                        ],
                        "@type": "BTProductRefOrValue"
                    },
                    "@type": "BTProductOrderItem"
                }
            ],
            "@type": "BTProductOrderItem"
        }
    ],
    "relatedParty": [
        {
            "id"           : "CUG5002237010" ,
            "role"         : "BtCug"         ,
            "@referredType": "Customer"      ,
            "@type"        : "BTRelatedParty"
        },
        {
            "id": "-1",
            "role": "PrimaryOrderContact",
            "contactMedium": [
                {
                    "mediumType": "email",
                    "characteristic": {
                        "emailAddress": "ptemail1@gmail.com",
                        "contactType" : "Primary Work"
                    }
                }
            ],
            "@type": "BTRelatedParty",
            "@referredType": "Individual"
        }
    ],
    "@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
    • This includes expediting SoGEA and FTTP provide orders by setting the Expedite product characteristic to 'Y'
  • 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" 
}

Expedite on Amend

{
    "requestedCompletionDate": "2022-12-14T00:00:00Z",
    "productOrderItem": [
        {
            "id": "100",
            "internalId": "00012233",
            "action": "add",
            "product": {
                "productOffering": {"id": "E0000432"},
                "productCharacteristic": [ {"name": "Expedite", "value": "Y"} ],
                "@type": "BTProductRefOrValue"
            },
            "appointment": {
                "id"              : "A42D0BDFR"           ,
                "appointmentStart": "2022-12-14T08:00:00Z",
                "BESAppointmentId": "A42D0BDFR"
            },
            "note": {
                "text" : "This is hazard note",
                "type" : "HazardNote"         ,
                "@type": "BTNote"
            },
            "@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 accepted, the request is further validated and a new ProductOrderCreateEvent KSU will be sent. That ProductOrderCreateEvent could contain an error if there was a subsequent problem. If the amend request is fully validated, a chain of product order state change events will follow as the amendment is propagated to downstream orders. 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 successfully cancelled downstream.

Request Method & URI

POST /hubco/tmf/productOrderingManagement/v4/cancelOrder

Request 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
  • Order is in waiters list
  • Cancelled ECC refused
  • Order is in Planned stage

 

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.

Cancel product order create event

{
	"event": {
		"cancelProductOrder": {
			"@type": "BTCancelProductOrder",
			"state": "inProgress",
			"productOrder": {
				"id": "O-20211120210"
			}
		}
	},
	"eventType": "CancelProductOrderCreateEvent",
	"eventTime": "2024-06-05T14:44:38.539Z",
	"eventId": "720fdb33-6b2f-bfb1-523b-a2274b3c3a05"
}

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
acknowledged acknowledged
assessingCancellation AcceptedByBTWwBC
assessingCancellation Cancellation Request
assessingCancellation CancellationAccepted
assessingCancellation CancellationRejected
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 CancellationRejected
inProgress CancelledBTWwBCService
inProgress CommittedByBTWwBC
inProgress CompletedBTWwBCService
inProgress DelayedBySupplier
inProgress DisconnectEsideCopperByBTWwbc
inProgress ECCApply
inProgress ECCReminder
inProgress FlaggedForAttention
inProgress In Progress
inProgress inProgress
inProgress NoORDSSRMServiceRequired
inProgress PendingWithBTWwBC
rejected AmendmentRejected
rejected CancellationRejected
 

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

Back to top