Invoicing API v2

Develop your own tools to track invoice files, and keep others updated about their status.

Learn more:

Overview

This API allows you to access your Akamai invoices.

Who should use this API

Use this API if you administer an Akamai-accelerated website, and want to develop your own tools to track invoice files and keep others in your organization updated about their status. Use it also to compare your invoices with your monthly usage.

Getting started

Before using the Beta API for the first time:

  • Review Get Started for API tools that Akamai provides.

  • Review Authorize Your Client to create your Akamai API access credentials and authorizations. As detailed in The API Identity Model, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • If you want to use this API to compare your final bill with your usage data, you need a separate token to provision the Billing Center API.

  • Some API operations require contractId and productId identifiers. They are both available programmatically from the Contracts API. The Invoicing API allows access to any contract for which you have permission to view invoicing data.

  • Some API operations require an account identifier. If it’s not already available, you can access it with the Property Manager API from listing contracts as described above. Select the top-level accountId member and remove the act_ prefix.

  • If you need help with the API, provide feedback with the Akamai developer community, or else contact Technical Support for help interpreting your invoice data.

Resources

The Invoicing API supports the set of operations listed below. See Getting Started for information on obtaining valid accountId, contractId, and productId values.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Notifications  
List Notifications GET /invoicing-api/v2/accounts/{accountId}/notifications
Create a Notification POST /invoicing-api/v2/accounts/{accountId}/notifications
Get a Notification GET /invoicing-api/v2/accounts/{accountId}/notifications/{notificationId}
Modify a Notification PUT /invoicing-api/v2/accounts/{accountId}/notifications/{notificationId}
Remove a Notification DELETE /invoicing-api/v2/accounts/{accountId}/notifications/{notificationId}
Invoices  
List Account’s Invoices GET /invoicing-api/v2/accounts/{accountId}/invoices{?month,year}
List Contract’s Invoices GET /invoicing-api/v2/contracts/{contractId}/invoices{?month,year}
List Contract’s Invoice Files GET /invoicing-api/v2/contracts/{contractId}/invoices/{invoiceNumber}/files
Download an Invoice File GET /invoicing-api/v2/contracts/{contractId}/invoices/{invoiceNumber}/files/{filename}
Geobilling  
Download Geobilling Files GET /invoicing-api/v2/contracts/{contractId}/products/{productId}/geo-billing-files{?day,month,year}

List notifications

Notifications inform a set of users whenever there are changes to an invoice. This operation lists all available notifications.

GET /invoicing-api/v2/accounts/{accountId}/notifications

Sample: /invoicing-api/v2/accounts/1-XYZ/notifications

Parameter Type Sample Description
URL parameters
accountId String 1-XYZ Identifies the account under which data is aggregated.

Status 200 application/json

Response:

[
    {
        "status": "ACTIVE",
        "contractIds": [
            "1-3CV382"
        ],
        "title": "Billing Center Invoice Notification",
        "id": 2584,
        "modificationDate": "2015-01-01T00:00:00Z",
        "creationDate": "2015-01-01T00:00:00Z",
        "emails": [
            "user@example.com"
        ]
    }
]

  1. Store the accountId as described in Getting Started.

  2. Make a GET request to /invoicing-api/v2/accounts/{accountId}/notifications.

Create a notification

This operation creates a new notification informing a set of users about invoices for a set of contracts. Each notification must specify a unique set of contracts. The request yields an error if the set of contractIds matches that of another notification.

POST /invoicing-api/v2/accounts/{accountId}/notifications

Sample: /invoicing-api/v2/accounts/1-XYZ/notifications

Content-Type: application/json

Request:

{
    "status": "ACTIVE",
    "title": "Billing Center Invoice Notification",
    "emails": [
        "user@example.com"
    ],
    "contractIds": [
        "1-3CV382"
    ]
}
Parameter Type Sample Description
URL parameters
accountId String 1-XYZ Identifies the account under which data is aggregated.

Status 200

  1. Store the accountId as described in Getting Started.

  2. Build a Notification request object such as the one shown below.

  3. Make a POST request to /invoicing-api/v2/accounts/{accountId}/notifications.

  4. Optionally store the response’s Location to access the new notification.

Get a notification

This operation accesses a specific notification, for example when making modifications to a specific notification.

GET /invoicing-api/v2/accounts/{accountId}/notifications/{notificationId}

Sample: /invoicing-api/v2/accounts/1-XYZ/notifications/2584

Parameter Type Sample Description
URL parameters
accountId String 1-XYZ Identifies the account under which data is aggregated.
notificationId Integer 2584 Identifies each notification.

Status 200 application/json

Response:

{
    "status": "ACTIVE",
    "contractIds": [
        "1-3CV382"
    ],
    "title": "Billing Center Invoice Notification",
    "id": 2584,
    "modificationDate": "2015-01-01T00:00:00Z",
    "creationDate": "2015-01-01T00:00:00Z",
    "emails": [
        "user@example.com"
    ]
}

  1. Store the accountId as described in Getting Started.

  2. Run the List Notifications operation, and store the appropriate item’s id as the notificationId.

  3. Make a GET request to /invoicing-api/v2/accounts/{accountId}/notifications/{notificationId}.

Modify a notification

This operation updates a notification. Any read-only members retained from a GET operation are ignored on subsequent PUTs.

PUT /invoicing-api/v2/accounts/{accountId}/notifications/{notificationId}

Sample: /invoicing-api/v2/accounts/1-XYZ/notifications/2584

Content-Type: application/json

Request:

{
    "status": "ACTIVE",
    "title": "Billing Center Invoice Notification",
    "emails": [
        "user@example.com"
    ],
    "contractIds": [
        "1-3CV382"
    ]
}
Parameter Type Sample Description
URL parameters
accountId String 1-XYZ Identifies the account under which data is aggregated.
notificationId Integer 2584 Identifies each notification.

Status 200

  1. Run the Get a Notification operation and store the response object.

  2. Optionally remove read-only Notification members: id, creationDate, and modificationDate.

  3. Modify any remaining Notification values as shown in the example below.

  4. Make a PUT request to the same URL as for Get a Notification: /invoicing-api/v2/accounts/{accountId}/notifications/{notificationId}.

Remove a notification

This operation deletes a notification.

DELETE /invoicing-api/v2/accounts/{accountId}/notifications/{notificationId}

Sample: /invoicing-api/v2/accounts/1-XYZ/notifications/2584

Parameter Type Sample Description
URL parameters
accountId String 1-XYZ Identifies the account under which data is aggregated.
notificationId Integer 2584 Identifies each notification.

Status 200

  1. Store the accountId as described in Getting Started.

  2. Run the List Notifications operation, and store the appropriate item’s id as the notificationId.

  3. Make a DELETE request to /invoicing-api/v2/accounts/{accountId}/notifications/{notificationId}.

List account’s invoices

For a given account, this operation lists available invoices for a specific month. A separate invoice, keyed by invoiceNumber, is available for each contract under the account.

GET /invoicing-api/v2/accounts/{accountId}/invoices{?month,year}

Sample: /invoicing-api/v2/accounts/1-XYZ/invoices?month=7&year=2015

Parameter Type Sample Description
URL parameters
accountId String 1-XYZ Identifies the account under which data is aggregated.
Optional query parameters
month Integer 7 The month for which data is aggregated. Must be paired with a year value.
year Integer 2015 The year for which data is aggregated. Must be paired with a month value.

Status 200 application/json

Response:

[
    {
        "files": [
            "1234567890_FINAL.pdf",
            "1234567890_FINAL.csv",
            "Akamai_1234567890.json"
        ],
        "fileVersion": "1",
        "invoiceDate": "2015-01-01",
        "invoiceDueDate": "2015-01-20",
        "invoiceTotal": 50000.42,
        "contractId": "1-ABCD",
        "invoiceNumber": "1234567890",
        "accountId": "1-XYZ"
    }
]

  1. Store the accountId as described in Getting Started.

  2. Determine the desired invoice’s year and month.

  3. Make a GET request to /invoicing-api/v2/accounts/{accountId}/invoices{?year,month}.

List contract’s invoices

For a given contract, this operation lists available invoices for a specific month. Separate invoices are keyed by invoiceNumber. Downloadable files are available either in the files array, or by running a separate List Contract’s Invoice Files operation.

GET /invoicing-api/v2/contracts/{contractId}/invoices{?month,year}

Sample: /invoicing-api/v2/contracts/1-ABCD/invoices?month=7&year=2015

Parameter Type Sample Description
URL parameters
contractId String 1-ABCD Identifies the contract under which data is aggregated.
Optional query parameters
month Integer 7 The month for which data is aggregated. Must be paired with a year value.
year Integer 2015 The year for which data is aggregated. Must be paired with a month value.

Status 200 application/json

Response:

[
    {
        "files": [
            "1234567890_FINAL.pdf",
            "1234567890_FINAL.csv",
            "Akamai_1234567890.json"
        ],
        "fileVersion": "1",
        "invoiceDate": "2015-01-01",
        "invoiceDueDate": "2015-01-20",
        "invoiceTotal": 50000.42,
        "contractId": "1-ABCD",
        "invoiceNumber": "1234567890",
        "accountId": "1-XYZ"
    }
]

  1. Determine the appropriate contractId as described in Getting Started.

  2. Set the desired invoice’s year and month.

  3. Make a GET request to /invoicing-api/v2/contracts/{contractId}/invoices{?year,month}.

List contract’s invoice files

For a given contract’s invoice, this lists available files, which often represent the same invoice data in different formats.

GET /invoicing-api/v2/contracts/{contractId}/invoices/{invoiceNumber}/files

Sample: /invoicing-api/v2/contracts/1-ABCD/invoices/1234567890/files

Parameter Type Sample Description
URL parameters
contractId String 1-ABCD Identifies the contract under which data is aggregated.
invoiceNumber Integer 1234567890 Identifies each unique invoice.

Status 200 application/json

Response:

[
    "1234567890_FINAL.csv",
    "1234567890_FINAL.pdf",
    "Akamai_1234567890.json"
]

  1. Run the List Contract’s Invoices operation and select the relevant invoice.

  2. Store the invoice’s contractId and invoiceNumber.

  3. Make a GET request to /invoicing-api/v2/contracts/{contractId}/invoices/{invoiceNumber}/files.

Download an invoice file

For a given contract’s invoice file, this operation accesses the content of the file. The downloadable file is available in the response body. The Content-Type depends on the format of the file you are downloading. The sample responses below show data in both JSON and CSV formats.

GET /invoicing-api/v2/contracts/{contractId}/invoices/{invoiceNumber}/files/{filename}

Sample: /invoicing-api/v2/contracts/1-ABCD/invoices/1234567890/files/Akamai_1234567890.json

Parameter Type Sample Description
URL parameters
contractId String 1-ABCD Identifies the contract under which data is aggregated.
invoiceNumber Integer 1234567890 Identifies each unique invoice.
filename String Akamai_1234567890.json Identifies each invoice file.

Status 200 application/json

Response:

{
    "INVOICE": {
        "INVOICE_ORDER_ID": "3-1ABCD12",
        "ACCOUNT_ID": "1-ABCDE",
        "FINALIZED_DATE": "2017-02-28",
        "INVOICE_TYPE": "Standard Invoice",
        "INVOICE_ID": 17331001020,
        "INVOICE_DATE": "2017-03-01",
        "END_CUSTOMER": [
            {
                "END_CUSTOMER_ACCOUNT_NAME": "Stream&Store, Inc.",
                "END_CUSTOMER_ORDER_ID": "3-1ABCD12",
                "END_CUSTOMER_ACCOUNT_ID": "1-ABCDE",
                "INVOICE_LINE": [
                    {
                        "PRODUCT": "Dynamic Site Delivery::HTTPS Option::SSL Network Access - 3rd Party Certificate",
                        "ITEM_END_DATE": "2017-03-31",
                        "PRODUCT_ID": "M-LC-159850",
                        "CREDITED_INVOICE_LINE_NUMBER": null,
                        "ITEM_UNIT_PRICE": 250,
                        "ITEM_DESC": "Dynamic Site Delivery::HTTPS Option::SSL Network Access - 3rd Party Certificate Committed ",
                        "ITEM_TYPE": "P",
                        "ITEM_TOTAL_SERVICES": 7500,
                        "ITEM_TOTAL_TAXES": 1500,
                        "EFFECTIVE_END_DATE": "2018-07-31",
                        "ITEM_UNITS": 30,
                        "ITEM_START_DATE": "2017-03-01",
                        "ITEM_TOTAL": 9000,
                        "CREDITED_INVOICE_NUMBER": null,
                        "UNIT_MEASURE": "Unit"
                    },
                    {
                        "PRODUCT": "Professional Services - Enterprise::Professional Services - Enterprise",
                        "ITEM_END_DATE": "2017-03-31",
                        "PRODUCT_ID": "M-LC-135915",
                        "CREDITED_INVOICE_LINE_NUMBER": null,
                        "ITEM_UNIT_PRICE": 1400,
                        "ITEM_DESC": "Professional Services - Enterprise::Professional Services - Enterprise",
                        "ITEM_TYPE": "P",
                        "ITEM_TOTAL_SERVICES": 1400,
                        "ITEM_TOTAL_TAXES": 280,
                        "EFFECTIVE_END_DATE": "2018-07-31",
                        "ITEM_UNITS": 1,
                        "ITEM_START_DATE": "2017-03-01",
                        "ITEM_TOTAL": 1680,
                        "CREDITED_INVOICE_NUMBER": null,
                        "UNIT_MEASURE": "Per Month"
                    },
                    {
                        "PRODUCT": "Akamai University Customer Training - Classroom",
                        "ITEM_END_DATE": "2017-03-31",
                        "PRODUCT_ID": "M-LC-133443",
                        "CREDITED_INVOICE_LINE_NUMBER": null,
                        "ITEM_UNIT_PRICE": 110,
                        "ITEM_DESC": "Akamai University Customer Training - Classroom Committed ",
                        "ITEM_TYPE": "P",
                        "ITEM_TOTAL_SERVICES": 110,
                        "ITEM_TOTAL_TAXES": 22,
                        "EFFECTIVE_END_DATE": "2018-07-31",
                        "ITEM_UNITS": 1,
                        "ITEM_START_DATE": "2017-03-01",
                        "ITEM_TOTAL": 132,
                        "CREDITED_INVOICE_NUMBER": null,
                        "UNIT_MEASURE": "Each"
                    },
                    {
                        "PRODUCT": "Dynamic Site Delivery::HTTPS Option",
                        "ITEM_END_DATE": "2017-03-31",
                        "PRODUCT_ID": "M-LC-121907",
                        "CREDITED_INVOICE_LINE_NUMBER": null,
                        "ITEM_UNIT_PRICE": 24672,
                        "ITEM_DESC": "HTTPS \u2013 Custom Certificate \u2013 Dynamic Site Delivery",
                        "ITEM_TYPE": "P",
                        "ITEM_TOTAL_SERVICES": 24672,
                        "ITEM_TOTAL_TAXES": 4934.4,
                        "EFFECTIVE_END_DATE": "2018-07-31",
                        "ITEM_UNITS": 1,
                        "ITEM_START_DATE": "2017-03-01",
                        "ITEM_TOTAL": 29606.4,
                        "CREDITED_INVOICE_NUMBER": null,
                        "UNIT_MEASURE": "Base Fee"
                    }
                ],
                "END_CUSTOMER_EXTERNAL_REFERENCE": null
            },
            {
                "END_CUSTOMER_ACCOUNT_NAME": "Stream&Store, Inc.",
                "END_CUSTOMER_ORDER_ID": "M-1ABCD13",
                "END_CUSTOMER_ACCOUNT_ID": "1-ABCDE",
                "INVOICE_LINE": [
                    {
                        "PRODUCT": "Dynamic Site Delivery::China CDN",
                        "ITEM_END_DATE": "2017-03-31",
                        "PRODUCT_ID": "M-LC-122113",
                        "CREDITED_INVOICE_LINE_NUMBER": null,
                        "ITEM_UNIT_PRICE": 1413,
                        "ITEM_DESC": "Dynamic Site Delivery::China CDN",
                        "ITEM_TYPE": "P",
                        "ITEM_TOTAL_SERVICES": 1413,
                        "ITEM_TOTAL_TAXES": 282.6,
                        "EFFECTIVE_END_DATE": "2018-07-31",
                        "ITEM_UNITS": 1,
                        "ITEM_START_DATE": "2017-03-01",
                        "ITEM_TOTAL": 1695.6,
                        "CREDITED_INVOICE_NUMBER": null,
                        "UNIT_MEASURE": "Per Month"
                    }
                ],
                "END_CUSTOMER_EXTERNAL_REFERENCE": null
            }
        ],
        "INVOICE_CURRENCY": "GBP",
        "PO_NUMBER": null,
        "INVOICE_VERSION": 1,
        "ACCOUNT_NAME": "Stream&Store, Inc."
    }
}

Status 200 text/csv

Response:

ACCOUNT_ID,ACCOUNT_NAME,INVOICE_START_DATE,INVOICE_ID,ITEM_START_DATE,ITEM_END_DATE,UNIT_MEASURE,PRODUCT_LINE,PRODUCT,PRODUCT_ID,ITEM_DESC,ITEM_SPEC,CUST_CURRENCY,ITEM_CURRENCY,ITEM_UNITS,CUST_UNIT_PRICE,ITEM_UNIT_PRICE,CUST_TOTAL_SERVICES,ITEM_TOTAL_SERVICES,CUST_TAXES,CUST_TOTAL,ITEM_TOTAL
1-ABCDE,"Stream&Store, Inc.",11/01/2016,1611344369,10/01/2016,10/31/2016,GB,Content Delivery Services,EdgeSuite with Flash,00322519,Adjustment to prior month based on tier achieved,Usage,GBP,GBP,3100,0,-.38,0,-1178,-176.7,0,-1354.7
1-ABCDE,"Stream&Store, Inc.",11/01/2016,1611344369,11/01/2016,11/30/2016,GB,Content Delivery Services,EdgeSuite Delivery Edition,00322519,EdgeSuite with Flash Committed ,Committed,GBP,GBP,3100,0,.38,0,1178,176.7,0,1354.7
1-ABCDE,"Stream&Store, Inc.",11/01/2016,1611344369,10/01/2016,10/31/2016,GB,Content Delivery Services,EdgeSuite with Flash,00322519,10536 GB of EdgeSuite with Flash Usage ,Usage,GBP,GBP,10536,0,.2959,0,3117.6,467.64,0,3585.24
1-ABCDE,"Stream&Store, Inc.",11/01/2016,1611344369,10/01/2016,10/31/2016,GB,Content Delivery Services,EdgeSuite with Flash,00322519,10536 GB of EdgeSuite with Flash Usage ,Usage,GBP,GBP,10536,0,.2959,0,3117.6,467.64,0,3585.24

  1. Run the List Contract’s Invoices operation and select the relevant invoice.

  2. Store the invoice’s contractId and invoiceNumber.

  3. Run the List Contract’s Invoice Files operation and store one of the filename values from the response’s array.

  4. URL-encode the filename.

  5. Make a GET request to /invoicing-api/v2/contracts/{contractId}/invoices/{invoiceNumber}/files/{filename}.

Download geobilling files

This operation provides details on invoicing for each geographic zone within the Akamai network. The downloadable file is available in the response body, formatted as a gzip-compressed CSV. The Param-md5-uncompressed response header provides an md5 checksum for the uncompressed file. (The sample response below shows uncompressed data.) See below for information on each geographic code. For information on how to interpret SUB_CUST_ID values, see the Wholesale Delivery User Guide.

GET /invoicing-api/v2/contracts/{contractId}/products/{productId}/geo-billing-files{?day,month,year}

Sample: /invoicing-api/v2/contracts/1-ABCD/products/1-ABC012/geo-billing-files?day=1&month=7&year=2015

Parameter Type Sample Description
URL parameters
contractId String 1-ABCD Identifies the contract under which data is aggregated.
productId String 1-ABC012 Identifies the product under which data is aggregated.
Required query parameters
day Integer 1 The day for which data is aggregated. Must be specified along with year and month values.
month Integer 7 The month for which data is aggregated. Must be specified along with year and day values.
year Integer 2015 The year for which data is aggregated. Must be specified along with month and day values.

Status 200 application/gzip

Response:

2/27/17,3-1ABCD12,BILLED,Wholesale Delivery::Wholesale Delivery,10,,
SUB_CUST_ID,GEO_ID,TOTAL MB,TOTAL HTTP HITS,TOTAL HTTPS HITS,TOTAL HTTP MB,TOTAL HTTPS MB
780a860f-0d10-4e97-8294-521bd32226a3,5,0,0,0,0,0
e5883297-232f-4ff5-8bbe-5d8aaf1bbd98,1,0.005022,0,1,0,0.005022
ce09e088-db21-4ad9-bc74-d124c4b7105f,1,1.358989,12,86,0.006612,1.352377
f91131a5-c5a8-4364-97f7-6a182ba2e52a,3,0.001057,1,0,0.001057,0
75685627-b357-44c2-8689-e86423190dda,8,0.005024,0,1,0,0.005024
f5e3da5e-ef67-478f-abd3-2e5f754a461c,5,7397.594389,0,57348,0,7397.594389
4d807c34-47b2-4ea8-9964-928cb15678ed,1,0.005023,0,1,0,0.005023
275db8a8-522c-4d3d-8589-7754c79a47da,5,0,0,0,0,0
116d3af4-96ed-4036-af02-59761c452de7,6,2698.890821,106250,1,2698.886061,0.00476
cf0ec3ef-ed8e-4c5f-87d2-181f3aa813e0,1,0.16569,210,0,0.16569,0

  1. Determine the appropriate contractId as described in Getting Started.

  2. Determine the appropriate productId as described in Getting Started.

  3. Determine the billing period’s desired year, month, and day.

  4. Make a GET request to /invoicing-api/v2/contracts/{contractId}/products/{productId}/geo-billing-files{?year,month,day}.

This operation’s CSV data uses the following system of GEO_ID codes:

Code Location
0 Any location that can’t be mapped to any of the regions below
1 North America
2 South America
3 Europe, the Middle East, and Africa
4 Australia and New Zealand
5 Japan
6 India
7 China
8 Remaining Asia and Pacific region

Data

This section details the data structures the API exchanges.

Download this API’s JSON schemas.

Notification

Specifies a set of people to notify whenever an invoice is available for a set of contracts.

Sample GET:

{
    "status": "ACTIVE",
    "title": "Billing Center Invoice Notification",
    "contractIds": [
        "1-3CV382"
    ],
    "emails": [
        "user@example.com"
    ],
    "modificationDate": "2015-01-01T00:00:00Z",
    "creationDate": "2015-01-01T00:00:00Z",
    "id": 2584
}

Notification members  

Member Type Required Description
contractIds Array ✓ Lists string identifiers representing the range of contracts for which the notification applies. Each notification reports on a unique set of contracts.
creationDate String ○ Read-only. The time when the notification was created, ISO 8601-formatted.
emails Array ✓ Lists recipients’ email address strings.
id Integer ○ Read-only. Unique identifier for each notification.
modificationDate String ○ Read-only. The time of the notification’s most recent change, ISO 8601-formatted.
status Enumeration ✓ Either ACTIVE to notify recipients about changes to invoices, or SUSPENDED to disable a notification.
title String ✓ Descriptive title to identify each notification.

Invoice

Contains contract-specific invoice data. All members are read-only and always present in GET responses.

Sample GET:

[
    {
        "files": [
            "1234567890_FINAL.pdf",
            "1234567890_FINAL.csv",
            "Akamai_1234567890.json"
        ],
        "fileVersion": "1",
        "invoiceDate": "2015-01-01",
        "invoiceDueDate": "2015-01-20",
        "invoiceTotal": 50000.42,
        "invoiceNumber": "1234567890",
        "accountId": "1-XYZ",
        "contractId": "1-ABCD"
    }
]

Invoice members  

Member Type Required Description
accountId String ✓ Unique identifier for the account to which the invoice applies. Corresponds to the InvoiceFile object’s ACCOUNT_ID.
contractId String ✓ Unique identifier for the contract to which the invoice applies.
fileVersion String ✓ An integer version string that identifies any changes to the set of files, incrementing when a file is added or modified.
files Array ✓ Identifies each invoice filename. Separate files are typically available in JSON, PDF, and CSV formats.
invoiceDate String ✓ The invoice’s published date, formatted as ISO–8601 YYYY-MM-DD. Corresponds to the InvoiceFile object’s INVOICE_DATE.
invoiceDueDate String ✓ The invoice’s last permissible published date, formatted as ISO–8601 YYYY-MM-DD.
invoiceNumber String ✓ Unique identifier for the invoice. Corresponds to the InvoiceFile object’s INVOICE_ID.
invoiceTotal Number ✓ The amount billed, measured in U.S. dollars. Corresponds to the sum of all of the InvoiceFile object’s ITEM_TOTAL values after the currency is normalized.

InvoiceFile

Encapsulates detailed invoice information available in a JSON file download.

Sample GET:

{
    "INVOICE": {
        "INVOICE_ORDER_ID": "3-1ABCD12",
        "ACCOUNT_ID": "1-ABCDE",
        "FINALIZED_DATE": "2017-02-28",
        "INVOICE_TYPE": "Standard Invoice",
        "INVOICE_ID": 17331001020,
        "INVOICE_DATE": "2017-03-01",
        "END_CUSTOMER": [
            {
                "END_CUSTOMER_ACCOUNT_NAME": "Stream&Store, Inc.",
                "END_CUSTOMER_ORDER_ID": "3-1ABCD12",
                "END_CUSTOMER_ACCOUNT_ID": "1-ABCDE",
                "INVOICE_LINE": [
                    {
                        "PRODUCT": "Dynamic Site Delivery::HTTPS Option::SSL Network Access - 3rd Party Certificate",
                        "ITEM_END_DATE": "2017-03-31",
                        "PRODUCT_ID": "M-LC-159850",
                        "CREDITED_INVOICE_LINE_NUMBER": null,
                        "ITEM_UNIT_PRICE": 250,
                        "ITEM_TOTAL_SERVICES": 7500,
                        "ITEM_TYPE": "P",
                        "ITEM_DESC": "Dynamic Site Delivery::HTTPS Option::SSL Network Access - 3rd Party Certificate Committed ",
                        "ITEM_TOTAL_TAXES": 1500,
                        "EFFECTIVE_END_DATE": "2018-07-31",
                        "ITEM_UNITS": 30,
                        "ITEM_START_DATE": "2017-03-01",
                        "ITEM_TOTAL": 9000,
                        "CREDITED_INVOICE_NUMBER": null,
                        "UNIT_MEASURE": "Unit"
                    },
                    {
                        "PRODUCT": "Professional Services - Enterprise::Professional Services - Enterprise",
                        "ITEM_END_DATE": "2017-03-31",
                        "PRODUCT_ID": "M-LC-135915",
                        "CREDITED_INVOICE_LINE_NUMBER": null,
                        "ITEM_UNIT_PRICE": 1400,
                        "ITEM_TOTAL_SERVICES": 1400,
                        "ITEM_TYPE": "P",
                        "ITEM_DESC": "Professional Services - Enterprise::Professional Services - Enterprise",
                        "ITEM_TOTAL_TAXES": 280,
                        "EFFECTIVE_END_DATE": "2018-07-31",
                        "ITEM_UNITS": 1,
                        "ITEM_START_DATE": "2017-03-01",
                        "ITEM_TOTAL": 1680,
                        "CREDITED_INVOICE_NUMBER": null,
                        "UNIT_MEASURE": "Per Month"
                    },
                    {
                        "PRODUCT": "Akamai University Customer Training - Classroom",
                        "ITEM_END_DATE": "2017-03-31",
                        "PRODUCT_ID": "M-LC-133443",
                        "CREDITED_INVOICE_LINE_NUMBER": null,
                        "ITEM_UNIT_PRICE": 110,
                        "ITEM_TOTAL_SERVICES": 110,
                        "ITEM_TYPE": "P",
                        "ITEM_DESC": "Akamai University Customer Training - Classroom Committed ",
                        "ITEM_TOTAL_TAXES": 22,
                        "EFFECTIVE_END_DATE": "2018-07-31",
                        "ITEM_UNITS": 1,
                        "ITEM_START_DATE": "2017-03-01",
                        "ITEM_TOTAL": 132,
                        "CREDITED_INVOICE_NUMBER": null,
                        "UNIT_MEASURE": "Each"
                    },
                    {
                        "PRODUCT": "Dynamic Site Delivery::HTTPS Option",
                        "ITEM_END_DATE": "2017-03-31",
                        "PRODUCT_ID": "M-LC-121907",
                        "CREDITED_INVOICE_LINE_NUMBER": null,
                        "ITEM_UNIT_PRICE": 24672,
                        "ITEM_TOTAL_SERVICES": 24672,
                        "ITEM_TYPE": "P",
                        "ITEM_DESC": "HTTPS \u2013 Custom Certificate \u2013 Dynamic Site Delivery",
                        "ITEM_TOTAL_TAXES": 4934.4,
                        "EFFECTIVE_END_DATE": "2018-07-31",
                        "ITEM_UNITS": 1,
                        "ITEM_START_DATE": "2017-03-01",
                        "ITEM_TOTAL": 29606.4,
                        "CREDITED_INVOICE_NUMBER": null,
                        "UNIT_MEASURE": "Base Fee"
                    }
                ],
                "END_CUSTOMER_EXTERNAL_REFERENCE": null
            },
            {
                "END_CUSTOMER_ACCOUNT_NAME": "Stream&Store, Inc.",
                "END_CUSTOMER_ORDER_ID": "M-1ABCD13",
                "END_CUSTOMER_ACCOUNT_ID": "1-ABCDE",
                "INVOICE_LINE": [
                    {
                        "PRODUCT": "Dynamic Site Delivery::China CDN",
                        "ITEM_END_DATE": "2017-03-31",
                        "PRODUCT_ID": "M-LC-122113",
                        "CREDITED_INVOICE_LINE_NUMBER": null,
                        "ITEM_UNIT_PRICE": 1413,
                        "ITEM_TOTAL_SERVICES": 1413,
                        "ITEM_TYPE": "P",
                        "ITEM_DESC": "Dynamic Site Delivery::China CDN",
                        "ITEM_TOTAL_TAXES": 282.6,
                        "EFFECTIVE_END_DATE": "2018-07-31",
                        "ITEM_UNITS": 1,
                        "ITEM_START_DATE": "2017-03-01",
                        "ITEM_TOTAL": 1695.6,
                        "CREDITED_INVOICE_NUMBER": null,
                        "UNIT_MEASURE": "Per Month"
                    }
                ],
                "END_CUSTOMER_EXTERNAL_REFERENCE": null
            }
        ],
        "ACCOUNT_NAME": "Stream&Store, Inc.",
        "PO_NUMBER": null,
        "INVOICE_VERSION": 1,
        "INVOICE_CURRENCY": "GBP"
    }
}

InvoiceFile members  

Member Type Required Description
INVOICE InvoiceFile.INVOICE ✓ All invoice file data is encapsulated within this top-level member.
InvoiceFile.INVOICE: All invoice file data is encapsulated within this top-level member.
ACCOUNT_ID String ✓ Unique identifier for the account this invoice reflects. Corresponds to the Invoice object’s accountId.
ACCOUNT_NAME String ✓ The name for the account this invoice reflects.
END_CUSTOMER InvoiceFile.INVOICE.END_CUSTOMER[] ✓ Collects products and services purchased as a bundle.
FINALIZED_DATE String ✓ Date when final values have been calculated, formatted as ISO–8601 YYYY-MM-DD.
INVOICE_CURRENCY String ✓ Three-letter ISO 4217 code indicating the currency that measures all totals.
INVOICE_DATE String ✓ Date when the invoice was issued, formatted as ISO–8601 YYYY-MM-DD. Corresponds to the Invoice object’s invoiceDate.
INVOICE_ID Integer ✓ Unique identifier for each invoice. Corresponds to the Invoice object’s invoiceNumber.
INVOICE_ORDER_ID String ✓ Unique identifier for the purchase order this invoice reflects.
INVOICE_TYPE String ✓ The overall category for the invoice, such as Standard Invoice or Credit Memo for adjustments.
INVOICE_VERSION Integer ✓ Invoices are versioned in case they later need to be adjusted.
PO_NUMBER String ✓ The purchase order number. Value may be null.
InvoiceFile.INVOICE.END_CUSTOMER[]: Collects products and services purchased as a bundle.
END_CUSTOMER_ACCOUNT_ID String ✓ The ACCOUNT_ID under which this bundle of services was purchased.
END_CUSTOMER_ACCOUNT_NAME String ✓ The ACCOUNT_NAME under which this bundle of services was purchased.
END_CUSTOMER_EXTERNAL_REFERENCE String ✓ An optional identifier for which the value may be null.
END_CUSTOMER_ORDER_ID String ✓ The INVOICE_ORDER_ID under which this bundle of services was purchased.
INVOICE_LINE InvoiceFile.INVOICE.END_CUSTOMER[].INVOICE_LINE[] ✓ Encapsulates invoice items aggregated by product, corresponding to each row of CSV data.
InvoiceFile.INVOICE.END_CUSTOMER[].INVOICE_LINE[]: Encapsulates invoice items aggregated by product, corresponding to each row of CSV data.
CREDITED_INVOICE_LINE_NUMBER String ✓ In case this total reflects an adjusted value, this indexes the earlier invoice’s INVOICE_LINE where the error occurred. This value is usually null.
CREDITED_INVOICE_NUMBER String ✓ In case this total reflects an adjusted value, this identifies the INVOICE_ID that contains the error. This value is usually null.
EFFECTIVE_END_DATE String ✓ Indicates when the measured service would expire under the contract, formatted as ISO–8601 YYYY-MM-DD.
ITEM_DESC String ✓ Describes the product.
ITEM_END_DATE String ✓ The end of the measured term, formatted as ISO–8601 YYYY-MM-DD.
ITEM_START_DATE String ✓ The start of the measured term, formatted as ISO–8601 YYYY-MM-DD.
ITEM_TOTAL Number ✓ The sum of ITEM_TOTAL_SERVICES and ITEM_TOTAL_TAXES. The sum of all these values corresponds to the Invoice object’s invoiceTotal, where the latter value is normalized is U.S. dollar terms.
ITEM_TOTAL_SERVICES Integer ✓ The total for all provided services.
ITEM_TOTAL_TAXES Number ✓ All additional taxes based on the ITEM_TOTAL_SERVICES.
ITEM_TYPE Enumeration ✓ The type of charge on an invoice. Possible values are B for bursting charges, C for true-up period unit commit charges, F for arrears commit charges, P for pre-bill commit charges, R where a previously prebilled commit is adjusted due to having reached re-pricing tiers, S for non-recurring commit charges, U for usage charges, X for super bursting charges, Z for true-up revenue commit charges, and AU for usage period commit adjustments.
ITEM_UNITS Integer ✓ The number of priced units, typically 1 for individual items or the number of days for a term of service.
ITEM_UNIT_PRICE Integer ✓ The price per ITEM_UNITS.
PRODUCT String ✓ Description of the invoiced product.
PRODUCT_ID String ✓ Unique identifier for each invoiced product.
UNIT_MEASURE String ✓ Characterizes the unit of sale or term of service.

Errors

This section tells you what you need to know about the Invoicing API’s error response format, and details the range of HTTP status codes the API produces.

Error responses

The API produces JSON errors as in the following sample. See the sections below for details on each data member.

{
  "details": [
    {
      "field": "year",
      "code": "year.date.year.missing",
      "message": "Month parameter cannot be provided without year parameter.",
      "data": {
        "field": "year",
        "value": "null"
      }
    }
  ],
  "code": "validation.failure",
  "title": "Validation failure",
  "incidentId": "361cd072-e213-4c4e-984d-631be108a1fe",
  "resolution": null,
  "helpUrl": null
}

Error members

Member Type Description
Required
details Error.details[] Each array member object encodes context for the failed request, such as malformed query parameter field values.
code String A descriptive code that corresponds to overall HTTP status.
incidentId String A logging key useful when communicating about problems with Technical Support representatives.
title String A descriptive title that corresponds to overall HTTP status.
Optional
helpUrl String Deprecated.
resolution String Deprecated.

Error.details[]  

Member Type Description
Required
code String A descriptive identifier for each problem.
message String A description of the problem.
Optional
data Object A loosely structured object that, when available, encapsulates the set of erroneous input values.
field String Indicates the request’s parameter field for which there is a problem.

HTTP status codes

The API produces the following set of HTTP status codes for both success and failure scenarios:

Code Description
200 Successful request.
201 Resource successfully created.
204 Request succeeded, but no data is available for the requested parameters.
401 Authorization error.
403 Access is forbidden.
404 Resource not found.
500 Server error.

Last modified: 4/10/2017