Invoicing API 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

Operation Method Endpoint
Notifications   (download RAML)
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   (download RAML)
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 RAML)
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

Last modified: 4/10/2017