This guide provides technical context, product rules, and implementation best practices for the BT Wholesale Quote Management REST API. Based on the TM Forum Quote Management API (TMF648) standards, this API replaces the legacy SOAP-based (v6) API and allows you to create and retrieve quotes for Ethernet and Optical products.
Generating a quote is optional. The generated Quote ID cannot be used for product ordering. The prices obtained through the Quote Management API are indicative, not firm prices.
1. Core architecture and constraints
The API is designed for synchronous operations, returning the pricing immediately within the response payload, eliminating the need for callback URLs.
- Quote retention: Quotes are saved for one month and can be retrieved using a GET request. Learn more in the Managing and interpreting quotes.
- Item limits: A single quote can contain up to 100 quote items.
- Product mixing: Products must be quoted individually; you cannot mix different products (e.g., E-Line and Ethernet Internet) within the same quote.
- Pricing nature: All API-generated pricing is indicative and non-binding; firm pricing is only confirmed at the order stage.
2. Product portfolio structures
A quote item typically associates a physical place with a product service. The structure of the payload depends on the specific product being quoted:
BT Wholesale Ethernet (BTWE)
BTWE enables customers to connect sites to the BT 21C core network and link them via virtual circuits. It supports point-to-point (E-Line), hub-and-spoke (E-Line), or any-to-any (E-LAN) configurations.
Service structures
- E-Line (point-to-point / hub-and-spoke):
- Structure: Uses a nested quoteItem hierarchy. You use a root quoteItem for the A-End's physical access. Underneath that, there is a nested quoteItem array for each B-End.
- Components: E-Line point-to-point decomposes into exactly three products:
- the A-End physical access (Etherway),
- the B-End physical access (Etherway), and
- the B-End virtual path (Etherflow Connected) that connects the B-End back to the A-End.
- Implementation: Follow the Quoting for E-Line tutorial for a step-by-step guide.
- E-LAN (any-to-yny):
- Structure: E-LAN has no A-End. Each site is quoted as an individual, flat quoteItem. To build a mesh, you submit multiple quoteItem objects in one request.
- Components: Each site uses a single flat quoteItem per site containing the physical access (e.g., Etherway) and the virtual path (e.g., Etherflow Dynamic) as siblings.
- Implementation: Follow the Quoting for E-LAN tutorial for a step-by-step guide.
Technical components
-
Etherway (physical access)
The physical delivery of the service to the premises.
- Bandwidths: 10Mbit/s to 10Gbit/s (Note: 1Mbit/s is generally legacy/copper).
- Supported access types:
- Etherway Fibre: EAD.
- Superfast GEA: FTTP, FTTC, SOGEA.
- Specialist access: Exchange Connect (EEC), Data Centre Connect (DCC), and Radio.
-
Etherflow (virtual circuit)
The logical throughput mapped over the Etherway.
- E-LAN: Uses EtherflowDynamicService (any-to-any).
- E-Line: Uses EtherflowConnectedService (point-to-point).
- Bandwidths: 0.2Mbit/s up to the parent Etherway's maximum speed.
-
Data Centre Connect (DCC)
- Capabilities: Provides 1Gbit/s and 10Gbit/s hand-offs.
- Delivery: Direct fibre connection via a patch panel within a co-located BT switch environment (no "local tail" required).
Wholesale Ethernet Internet
This bundled service delivers a layer 3 connection directly to the internet.
- Structure: Internet access has no A-End. Quotes require a single, flat quoteItem per site containing the physical access (e.g., Etherway) and the virtual path (e.g., Etherflow Internet) as siblings.
- Bandwidths: Etherway Fibre access ranges from 100Mbit/s to 10Gbit/s. The Etherflow Internet (EVC) ranges from 30Mbit/s to 10Gbit/s.
- Implementation: Follow the Quoting for Ethernet Internet tutorial for a step-by-step guide.
3. Site compatibility matrix
When structuring your API request, you must match the exact site identifier type to the supported Etherway service. Use the explicit schema names below:
|
Different site types |
Etherway Fibre |
Etherway OSA |
Etherway Exchange Connect |
Etherway GEA |
Etherway Data Centre |
Etherway Radio |
|---|---|---|---|---|---|---|
| PostcodeSite | Yes | Yes | Yes | Yes | Yes | Yes |
| CoordinateSite | Yes | Yes | Yes | No | No | Yes |
| DirectoryNumberSite | No | No | No | Yes | No | No |
| NadKeySite | Yes | Yes | Yes | Yes | No | Yes |
| UPRNSite | Yes | Yes | Yes | No | No | Yes |
| DataCentreSite | Yes | No | No | No | Yes | No |
| ExchangeConnectSite | No | No | Yes | No | No | No |
| AccessLineIdSite | No | No | No | Yes | No | No |
Note: To minimize new API versions being released with every new feature and to future-proof the API, some schema options are included but not yet active. Features like Etherway Radio, GEA FoD, and certain GEA FTTP bandwidths are reserved for future use and will be implemented when the functionality is introduced to the pricing tool.
4. Integration best practices
Rate limiting and efficiency
The API enforces a fair use policy and is rate-limited to ensure stability. Applications exceeding these limits may have access revoked.
- Rate limit headers: Your API responses will include headers detailing the specific limit set, the number of requests remaining in the current period, and the time until the limit resets.
- Batching vs. parallel requests: Do not send multiple concurrent transactions for the same site. Because the API caches downstream system calls, sending 10 separate requests for permutations at a single postcode is highly inefficient and may trigger downstream usage errors. Instead, combine them into a single request containing up to 100 quote items.
Testing environments
- Sandbox: A fully functional environment for onboarding and functional testing. Responses are not stubbed, but actual pricing will not be accurate and must not be used in production. Use the X-System-Environment header in the API response to confirm whether you are connecting to the sandbox or production environment.
- Troubleshooting: If you encounter HTTP errors, test your JSON payloads using tools like curl or Postman, and consult the API specification error codes. For more detailed product information, GEA bandwidth tables, and example scenario diagrams, please consult the relevant Product Handbook on BTWholesale.com or contact your BT Wholesale Account Manager.
The web-based pricing tool
To fully understand product structures and required payload inputs, it is highly recommended to use the BT Wholesale web-based pricing tool.
- Register for a BT Wholesale portal account.
- Navigate to 'My BT Wholesale', click 'App A-Z'.
- Locate the 'BT Wholesale Pricing Tool', and request access.
- Once approved, it will appear under 'My apps'.
Note: It can take a couple of days for access to be provided by the portal team.
GEA bandwidths reference table
| Bandwidth | Status |
|---|---|
| SOGEA 0.5:0.5 Mbit/s | Not yet implemented |
| SOGEA 40:10 Mbit/s | Available |
| SOGEA 80:20 Mbit/s | Available |
| FTTC 40:10 Mbit/s | Available |
| FTTC 80:20 Mbit/s | Available |
| FTTP 0.5:0.5 Mbit/s | Available |
| FTTP 40:10 Mbit/s | Available |
| FTTP 80:20 Mbit/s | Available |
| FTTP 115:20 Mbit/s | Available |
| FTTP 160:30 Mbit/s | Available |
| FTTP 220:20 Mbit/s | Available |
| FTTP 220:30 Mbit/s | Available |
| FTTP 330:30 Mbit/s | Available |
| FTTP 330:50 Mbit/s | Available |
| FTTP 500:165 Mbit/s | Available |
| FTTP 500:500 Mbit/s | Not yet implemented |
| FTTP 550:550 Mbit/s | Not yet implemented |
| FTTP 550:75 Mbit/s | Available |
| FTTP 1000:115 Mbit/s | Available |
| FTTP 1000:220 Mbit/s | Available |
| FTTP 1000:1000 Mbit/s | Not yet implemented |
| FTTP 1100:1100 Mbit/s | Not yet implemented |
| FoD 500:500 Kbit/s * | Not yet implemented |
| FoD 115:20 Mbit/s | Not yet implemented |
| FoD 160:30 Mbit/s | Not yet implemented |
| FoD 220:20 Mbit/s | Not yet implemented |
| FoD 220:30 Mbit/s | Not yet implemented |
| FoD 330:30 Mbit/s | Not yet implemented |
| FoD 330:50 Mbit/s | Not yet implemented |
| FoD 500:165 Mbit/s | Not yet implemented |
| FoD 500:500 Mbit/s | Not yet implemented |
| FoD 550:550 Mbit/s | Not yet implemented |
| FoD 550:75 Mbit/s | Not yet implemented |
| FoD 1000:115 Mbit/s | Not yet implemented |
| FoD 1000:220 Mbit/s | Not yet implemented |
| FoD 1000:1000 Mbit/s | Not yet implemented |
| FoD 1100:1100 Mbit/s | Not yet implemented |
Next steps
Learn more about the Quote Management API's practical implementation rules in the Quick start guide.
Or choose the tutorial that matches your connectivity requirements:
- Quoting for dedicated Ethernet (E-Line): Learn how to construct the nested payloads required to connect physical sites together via virtual circuits in point-to-point or hub-and-spoke configurations.
- Quoting for Ethernet LAN (E-LAN): Discover how to generate a quote for any-to-any connectivity, allowing multiple sites to communicate within a private network mesh.
- Quoting for Ethernet Internet: Follow the steps to build a quote for this bundled service, which delivers a layer 3 connection directly to the internet.
- Managing and interpreting quotes: Learn how to retrieve quotes by Id, how list and search quotes, and how to interpret the response headers and quote states.