Customer Bill

Lumen Customer Bill APIs allow you to find and retrieve one or several bills (also called invoices), and associated applied bill rated objects.

API Overview

Developers: Go to Getting Started for a full overview of APIs, resources, and implementation guides. Go to Documentation / Specification for OAS specifications.

Lumen Customer Bill APIs allow you to find and retrieve one or several bills (also called invoices) produced for a Lumen customer. A customer bill is an electronic or paper document produced at the end of the billing process. The bill gathers and displays different items (applied customer billing rates generated during the rating and billing processes) to be charged to a Lumen customer. It represents the total amount due for all the products during the billing period and all significant information like bill dates, bill reference, which is essentially a link you can click on to view/download a PDF copy of your invoices.

Retrieve a customer bill or a collection of customer bills depending on filter criteria.
Retrieve an applied customer billing rate or a collection of applied customer billing rates depending on filter criteria.

Customer Bill APIs are available to existing non-regulated enterprise North America customers only. All the Lumen customers who intend to use the APIs should request access to API Marketplace and complete the required authentication and authorization prerequisites before accessing the API. The Customer Bill Management API should be used by someone who is familiar with API interfaces, REST, and JSON.

The Customer Bill APIs provided easy access to the charges presented on invoices generated by Lumen.

Decrease Manual Steps: Customer Bill APIs enable self-service functionality where customers no longer need to log into a portal and swivel chair information. Using APIs you can consume Lumen services your way.
Enable Digital Delivery: By digitalizing bill attributes, the Customer Bill APIs allows customers to pull billing information and values into internal systems for analysis and management.
Accelerate Analysis: Customers can ingest bill information through their chosen systems and get deeper insights into their services.

Getting started

This API is available for Beta release only and is currently available to specific beta users. If you are interested in becoming a beta user, please see the support tab or use the Contact Us form in the main menu.

Enroll in Customer Bill APIs. Contact your account representative to complete the enrollment form.
Register user and API Apps. Once you have registered a user, you can create a Sandbox app (used for code development), and a Production app. Each client app will be provisioned with a unique set of credentials (consumer key and consumer secret). A Sandbox app will have test credentials while a Production app will have production credentials.
Obtain API keys. Once your enrollment is complete, your request for access will move from Pending status to Approved status. The registered user will receive an email informing them of the approved status.
Setup authorization. Using the Navigation bar go to Code Samples for sample code for setting up authorization.
Make your first call. Go to Documentation/Specification
- Click on the Authorization button and add your Sandbox credentials.
- Select the GET/customerBill API.
- Click on the "Try it out" button.
- Fill in the Parameters.
- Click the Execute button to see the response

When setting up your Apps in My Apps you can create a Sandbox app and a Production app. You will then have two different sets of Consumer Keys and Consumer Secrets.
Base URL Sandbox: https://api-test.lumen.com/
Base URL Prod: https://api.lumen.com/

The Sandbox (test) environment is available to developers to build initial code against. It is a snapshot of production type data so that you can try out requests and responses. The Sandbox is not meant to be used as a QA environment. It is also not meant to duplicate production, therefore data that exists in Production may not be present in the Sandbox environment. Sandbox does not represent the up-time expectations of Production. We recommend that you complete shakeout testing against Production, keeping in mind that all transactions will be live.

Go to Documentation/Specification to find OAS 3.0 (Swagger) documentation, as well as important information for setting up authorization.

Lumen APIs use RESTful design and JSON-encoded response with standard OAuth 2 Authorization protocols.

Base URL Test: https://api-test.centurylink.com/

Base URL Prod: https://api.centurylink.com/

API Guide: Customer Bill

Upon launch of the API on January 30, 2022, you can access up to 2 years of historic data in production. Historic data will continue to grow over time.
Sandbox is limited to data from June 2021 - November 2021

Use Customer Bill to search for invoices generated during a given period. You may search by billing account number (formatted 5-ABCD5678) or by invoice number (Customer Bill ID). The response will provide details on each invoice (bill document) for the given period. Details such as bill cycle, amount due, and tax are provided in the response. When available, a URL to the bill image is provided.

You can find detailed specs on the Documentation / Specification tab on the side navigation bar.

API Guide: Applied Bill Rate

Upon launch of the API on January 30, 2022, you can access up to one year of historic data in production. Historic data will continue to grow over time.
Sandbox is limited to data from June 2021 - November 2021

Use Applied Bill Rate to see for a given period, the breakdown of a bill by product with applied tax, tax excluded amount, and tax included amount.

Authentication / Authorization

Lumen supports the OAuth 2.0 client credentials authorization grant flow for external access by client-side applications.

Only existing Lumen customers can access Billing APIs. Please contact your Lumen account team to begin the enrollment process, or see the Support section for more information. Upon enrollment, you will receive instructions on how to get started. Once your application is approved you can go to Using OAuth 2.0 for detailed steps on getting a Bearer token using basic authorization base64 encoding.

Get your Authorization Bearer Token

You will use credentials for Sandbox and for Production
Tokens expire in 30 minutes. Call the Authorization server again to request a new token

Use basic authorization Base64 encoding where your username is the consumer key and password is the consumer secret

Authorization Header

Extract your bearer token from the response.

Authorization Body

Sample Code

curl --location --request POST 'https://api-test.lumen.com/oauth/token' \
--header 'Authorization: Basic clpxb1VtS0ZBMWtndlRVd05wVUFlY3lhdFI3SmtaNHI6QjhwWjYzRAbcDeFGHijk==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

Documentation / Specification

Code Samples

GET/CustomerBill
curl -X 'GET' \
'https://api-test.lumen.com/Billing/v1/CustomerBillManagement/customerBill?billingAccountNumber=123456789&startBillDate=2021-05-01&endBillDate=2021-11-30' \
-H 'accept: application/json;charset=utf-8' \
-H 'x-billing-account-number: 123456789' \
-H 'Authorization: Bearer KKN84oxzNRoHND1N1AbcDeFGHijk'

GET/CustomerBill/{id}
curl -X 'GET' \
'https://api-test.lumen.com/Billing/v1/CustomerBillManagement/customerBill/123456789' \
-H 'accept: application/json;charset=utf-8' \
-H 'x-billing-account-number: 123456789' \
-H 'Authorization: Bearer KKN84oxzNRoHND1N1AbcDeFGHijk'

GET/appliedCustomerBillingRate
curl -X 'GET' \
'https://api-test.lumen.com/Billing/v1/CustomerBillManagement/appliedCustomerBillingRate?billingAccountNumber=123456789&startBillDate=2021-05-01&endBillDate=2021-11-30' \
-H 'accept: application/json;charset=utf-8' \
-H 'x-billing-account-number: 123456789' \
-H 'Authorization: Bearer KKN84oxzNRoHND1N1AbcDeFGHijk'

Status and Codes

For GET/CustomerBill

Code	Message
401	Unauthorized. Invalid access token
401	Unauthorized. Access token expired
404	No data found for billingAccountID: XXXXXXXX
404	User not authorized for billingAccountID: XXXXXXXX
500	Invalid CurrencyCode found: XXXXXXXX
500	Invalid invoiceCurrencyCode found: XXXXXXXX
500	Internal server error

For GET/appliedCustomerBillingRate

Code	Message
400	Max allowed value for limit is 1000. Retry request by adjusting the limit param.
400	Date must be in format. Please retry request adjusting the date param
401	Unauthorized. Invalid access token
401	Access token expired
404	No data found for billingAccountID: XXXXXXXX
404	User not authorized for billingAccountID: XXXXXXXX
500	Internal server error

Support / Tools

Lumen API Marketplace provides support options to ensure you get the most out of your experience. For questions or issues with the Customer Bill API, please click here to contact us.

If you are a new customer and would like more information about our products please visit Lumen.com or one of our product sites.

This API interface is outside of the normal production Lumen-controlled functionality. Its usage requires a fairly technical level of knowledge by the end-user. Lumen cannot be responsible for the lack of technical knowledge or understanding of the technologies integrated with this interface and the resulting incorrect results or end-user environmental impacts. Problems with a client’s operating environments or any technical issues on the client’s side of the transaction are not handled or supported by Lumen. As such, normal Lumen production support processes will be allowed only in the event of a data issue if it is suspected that the extracted information is incorrect and only after the end-user validates proper usage of this API.

Minor version changes are backwards compatible and will be described in the Change Log section.

Major versions are used if changes are not backwards compatible. Major versions are indicated in the API URL such as api.lumen.com/Quoting/v1/. Major versioning will be communicated to API users through the header (where technically feasible) and in the change log. In some cases, Lumen may also email users to inform of deprecation and sunsetting plans.

Deprecation: API is no longer recommended for use although it may still be operational. Usually, a new version is available.
Deprecation Date: The date on which the new version is available, and the old version is no longer recommended for use.
Sunsetting: The API is being shut down as of the sunset date. The API may return error codes or maybe entirely unresponsive. Sometimes referred to as “wholly deprecate”