Invoicing API v3

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

Learn more:


Overview

The Invoicing API provides data about your Akamai invoices and credit memos.

This API offers a programmatic alternative to the Your bills, Bills history, and Notifications features available in the Billing Akamai Control Center interface.

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

Get started

To configure this API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named Invoicing, and set the access level to READ-WRITE.

  • 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 API.

  • Some API operations require contractId identifier. It’s available programmatically from the Contract API. The Invoicing API allows access to any contract for which you have permission to view invoicing data.

  • If you need help with the API, provide feedback with the Akamai developer community, or contact your Akamai representative for help understanding your data.

Rate limiting

This API imposes a rate limiting constraint of 500 requests per minute per account. Exceeding this limit results in a 429 error response. Consider this when calling successive operations as part of a loop.

All responses specify these rate limit headers:

  • X-RateLimit-Limit. The maximum number of requests allowed each minute.

  • X-RateLimit-Remaining. The number of allowed requests remaining. Except for any subsequent requests that reduce the number, this gradually increments until it reaches the X-RateLimit-Limit.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Invoices  
List invoices and credit memos for an account GET /invoicing-api/v3/invoices{?month}
List invoices and credit memos for a contract GET /invoicing-api/v3/contracts/{contractId}/invoices{?month}
Download an invoice or a credit memo file GET /invoicing-api/v3/contracts/{contractId}/invoices/{invoiceId}/download{?fileFormat}
Notifications  
List notifications for an account GET /invoicing-api/v3/notifications
Create a notification POST /invoicing-api/v3/notifications
Get a notification GET /invoicing-api/v3/notifications/{notificationId}
Modify a notification PUT /invoicing-api/v3/notifications/{notificationId}
Remove a notification DELETE /invoicing-api/v3/notifications/{notificationId}

List invoices and credit memos for an account

Returns invoices and credit memos for the current account and the selected month.

GET /invoicing-api/v3/invoices{?month}

Sample: /invoicing-api/v3/invoices?month=2020-07

Parameter Type Sample Description
Required query parameters
month String 2020-07 Selected billable usage period, expressed as an ISO 8601 datestamp (YYYY-MM).

Status 200 application/json

Object type: Invoice

Download schema: list-invoices-schema.json

Response body:

[
    {
        "invoiceId": 1234567890,
        "invoiceDate": "2021-01-01",
        "invoiceDueDate": "2021-01-20",
        "invoiceTotal": 50000.42,
        "invoiceCurrency": "USD",
        "invoiceType": "INVOICE",
        "contractId": "1-ABCD",
        "accountId": "1-XYZ",
        "files": [
            {
                "fileName": "InvoiceName_1-XYZ_1-ABCD_1234567890_FINAL_1.pdf",
                "fileFormat": "PDF",
                "fileVersion": 1
            },
            {
                "fileName": "1234567890_1.csv",
                "fileFormat": "CSV",
                "fileVersion": 1
            }
        ]
    },
    {
        "invoiceId": 8234567890,
        "invoiceDate": "2021-01-01",
        "invoiceDueDate": "2021-01-20",
        "invoiceTotal": -1020.71,
        "invoiceCurrency": "USD",
        "invoiceType": "CREDIT_MEMO",
        "contractId": "1-ABCD",
        "accountId": "1-XYZ",
        "files": [
            {
                "fileName": "CreditMemoName_1-XYZ_1-ABCD_8234567890_FINAL_1.pdf",
                "fileFormat": "PDF",
                "fileVersion": 2
            },
            {
                "fileName": "8234567890_1.csv",
                "fileFormat": "CSV",
                "fileVersion": 2
            }
        ]
    }
]

Status 204

  1. Determine the month for which you want data.

  2. Make a GET request to /invoicing-api/v3/invoices{?month}.

The operation responds with an Invoice object.

List invoices and credit memos for a contract

Returns invoices and credit memos for the specified contract and the selected month.

GET /invoicing-api/v3/contracts/{contractId}/invoices{?month}

Sample: /invoicing-api/v3/contracts/1-5QRKWT/invoices?month=2020-07

Parameter Type Sample Description
URL path parameters
contractId String 1-5QRKWT Identifies the contract that you want to see aggregated data from.
Required query parameters
month String 2020-07 Selected billable usage period, expressed as an ISO 8601 datestamp (YYYY-MM).

Status 200 application/json

Object type: Invoice

Download schema: list-invoices-schema.json

Response body:

[
    {
        "invoiceId": 1234567890,
        "invoiceDate": "2021-01-01",
        "invoiceDueDate": "2021-01-20",
        "invoiceTotal": 50000.42,
        "invoiceCurrency": "USD",
        "invoiceType": "INVOICE",
        "contractId": "1-ABCD",
        "accountId": "1-XYZ",
        "files": [
            {
                "fileName": "InvoiceName_1-XYZ_1-ABCD_1234567890_FINAL_1.pdf",
                "fileFormat": "PDF",
                "fileVersion": 1
            },
            {
                "fileName": "1234567890_1.csv",
                "fileFormat": "CSV",
                "fileVersion": 1
            }
        ]
    },
    {
        "invoiceId": 8234567890,
        "invoiceDate": "2021-01-01",
        "invoiceDueDate": "2021-01-20",
        "invoiceTotal": -1020.71,
        "invoiceCurrency": "USD",
        "invoiceType": "CREDIT_MEMO",
        "contractId": "1-ABCD",
        "accountId": "1-XYZ",
        "files": [
            {
                "fileName": "CreditMemoName_1-XYZ_1-ABCD_8234567890_FINAL_1.pdf",
                "fileFormat": "PDF",
                "fileVersion": 2
            },
            {
                "fileName": "8234567890_1.csv",
                "fileFormat": "CSV",
                "fileVersion": 2
            }
        ]
    }
]

Status 204

  1. Determine the appropriate contractId as described in Get started.

  2. Determine the month for which you want data.

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

The operation responds with an Invoice object.

Download an invoice or a credit memo file

Returns the content of the selected contract’s invoice or credit memo file. The downloadable file is available in the response body. The Content-Type depends on the format of the file you’re downloading.

GET /invoicing-api/v3/contracts/{contractId}/invoices/{invoiceId}/download{?fileFormat}

Sample: /invoicing-api/v3/contracts/1-5QRKWT/invoices/17331001020/download?fileFormat=PDF

Parameter Type Sample Description
URL path parameters
contractId String 1-5QRKWT Identifies the contract that you want to see aggregated data from.
invoiceId Integer 17331001020 Identifies the invoice or credit memo that you want to download.
Required query parameters
fileFormat Enumeration PDF File format of the invoice. These are the available values: PDF, CSV, and JSON.

Status 200

Status 204

  1. Determine the appropriate contractId as described in Get started.

  2. Run the List invoices and credit memos for an account or List invoices and credit memos for a contract operation to list available invoices. Store a invoiceId value assigned to the document that you want to download.

  3. Determine the appropriate fileFormat. These are the available values: PDF, CSV, and JSON.

  4. Make a GET request to /invoicing-api/v3/contracts/{contractId}/invoices/{invoiceId}/download{?fileFormat}.

List notifications for an account

Returns notifications for the current account. Notifications inform a set of users whenever there are changes to an invoice or credit memo.

GET /invoicing-api/v3/notifications

Status 200 application/json

Object type: Notification

Download schema: notifications-list-schema.json

Response body:

[
    {
        "notificationId": 25056,
        "notificationTitle": "Notification for 1-ABCDEF",
        "creationDate": "2020-12-09T08:30:14Z",
        "modificationDate": "2020-12-09T08:30:14Z",
        "notificationStatus": "ACTIVE",
        "emails": [
            "user@example.com"
        ],
        "contracts": [
            "1-ABCDEF"
        ]
    },
    {
        "notificationId": 25059,
        "notificationTitle": "Notification for 2-FEDCBA",
        "creationDate": "2020-12-09T08:30:14Z",
        "modificationDate": "2020-12-09T08:30:14Z",
        "notificationStatus": "SUSPENDED",
        "emails": [
            "user@example.com"
        ],
        "contracts": [
            "2-FEDCBA"
        ]
    }
]

Status 204

Create a notification

Creates a notification informing a set of users about new invoices or credit memos for a set of contracts. Each notification needs to specify a unique set of contracts. The request yields an error if the set of contractIds matches that of another notification.

POST /invoicing-api/v3/notifications

Content-Type: application/json

Object type: Notification

Download schema: create-update-notification-schema.json

Request body:

{
    "notificationTitle": "Notification for 1-ABCDEF",
    "notificationStatus": "ACTIVE",
    "emails": [
        "user@example.com"
    ],
    "contracts": [
        "1-ABCDEF"
    ]
}

Status 201 application/json

Headers:

Location: /invoicing-api/v3/notifications/2

Object type: Notification

Download schema: notification-schema.json

Response body:

{
    "notificationId": 25056,
    "notificationTitle": "Notification for 1-ABCDEF",
    "creationDate": "2020-12-09T08:30:14Z",
    "modificationDate": "2020-12-09T08:30:14Z",
    "notificationStatus": "ACTIVE",
    "emails": [
        "user@example.com"
    ],
    "contracts": [
        "1-ABCDEF"
    ]
}
  1. Build a Notification request object.

  2. POST the object to /invoicing-api/v3/notifications.

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

Get a notification

Accesses a specific notification, for example when making modifications to a specific notification.

GET /invoicing-api/v3/notifications/{notificationId}

Sample: /invoicing-api/v3/notifications/782131

Parameter Type Sample Description
URL path parameters
notificationId Integer 782131 Identifies the notification.

Status 200 application/json

Object type: Notification

Download schema: notification-schema.json

Response body:

{
    "notificationId": 25056,
    "notificationTitle": "Notification for 1-ABCDEF",
    "creationDate": "2020-12-09T08:30:14Z",
    "modificationDate": "2020-12-09T08:30:14Z",
    "notificationStatus": "ACTIVE",
    "emails": [
        "user@example.com"
    ],
    "contracts": [
        "1-ABCDEF"
    ]
}
  1. Run the List notifications operation to list available notifications. Store a notificationId value assigned to the notification that you want to access.

  2. Make a GET request to /invoicing-api/v3/notifications/{notificationId}.

The operation responds with a Notification object.

Modify a notification

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

PUT /invoicing-api/v3/notifications/{notificationId}

Sample: /invoicing-api/v3/notifications/782131

Content-Type: application/json

Object type: Notification

Download schema: create-update-notification-schema.json

Request body:

{
    "notificationTitle": "Notification for 1-ABCDEF",
    "notificationStatus": "ACTIVE",
    "emails": [
        "user@example.com"
    ],
    "contracts": [
        "1-ABCDEF"
    ]
}
Parameter Type Sample Description
URL path parameters
notificationId Integer 782131 Identifies the notification.

Status 200 application/json

Object type: Notification

Download schema: notification-schema.json

Response body:

{
    "notificationId": 25056,
    "notificationTitle": "Notification for 1-ABCDEF",
    "creationDate": "2020-12-09T08:30:14Z",
    "modificationDate": "2020-12-09T08:30:14Z",
    "notificationStatus": "ACTIVE",
    "emails": [
        "user@example.com"
    ],
    "contracts": [
        "1-ABCDEF"
    ]
}
  1. Run the List notifications operation to list available notifications. Store a notificationId value assigned to the notification that you want to modify.

  2. Run the Get a notification operation to access the notification that you want to modify.

  3. Modify the Notification object.

  4. PUT the object to /invoicing-api/v3/notifications/{notificationId}.

Remove a notification

Deletes a notification.

DELETE /invoicing-api/v3/notifications/{notificationId}

Sample: /invoicing-api/v3/notifications/782131

Parameter Type Sample Description
URL path parameters
notificationId Integer 782131 Identifies the notification.

Status 204

  1. Run the List notifications operation to list available notifications. Store a notificationId value assigned to the notification that you want to delete.

  2. Make a DELETE request to /invoicing-api/v3/notifications/{notificationId}.

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

Invoice

List of invoices and credit memos.

Download schema: invoice-schema.json

Sample GET response:

[
    {
        "invoiceId": 1234567890,
        "invoiceDate": "2021-01-01",
        "invoiceDueDate": "2021-01-20",
        "invoiceTotal": 50000.42,
        "invoiceCurrency": "USD",
        "invoiceType": "INVOICE",
        "contractId": "1-ABCD",
        "accountId": "1-XYZ",
        "files": [
            {
                "fileName": "InvoiceName_1-XYZ_1-ABCD_1234567890_FINAL_1.pdf",
                "fileFormat": "PDF",
                "fileVersion": 1
            },
            {
                "fileName": "1234567890_1.csv",
                "fileFormat": "CSV",
                "fileVersion": 1
            }
        ]
    },
    {
        "invoiceId": 8234567890,
        "invoiceDate": "2021-01-01",
        "invoiceDueDate": "2021-01-20",
        "invoiceTotal": -1020.71,
        "invoiceCurrency": "USD",
        "invoiceType": "CREDIT_MEMO",
        "contractId": "1-ABCD",
        "accountId": "1-XYZ",
        "files": [
            {
                "fileName": "CreditMemoName_1-XYZ_1-ABCD_8234567890_FINAL_1.pdf",
                "fileFormat": "PDF",
                "fileVersion": 2
            },
            {
                "fileName": "8234567890_1.csv",
                "fileFormat": "CSV",
                "fileVersion": 2
            }
        ]
    }
]

Invoice members

Member Type Required Description
Invoice: List of invoices and credit memos.
accountId String Identifies the account.
contractId String Identifies the contract the data reflects.
files Invoice.files[] Specifies invoice and credit memo files.
invoiceCurrency String Three-letter ISO 4217 code indicating the currency that measures all totals.
invoiceDate String The invoice’s or credit memo’s published date, formatted as ISO 8601 date.
invoiceDueDate String The invoice’s or credit memo’s due date.
invoiceId Integer Identifies the invoice or credit memo.
invoiceTotal Number The amount billed.
invoiceType Enumeration The overall category for the document, such as INVOICE or CREDIT_MEMO for adjustments.
Invoice.files[]: Specifies invoice and credit memo files.
fileFormat Enumeration The format of the file, either PDF, CSV, or JSON.
fileName String The name of the file.
fileVersion Integer The version of the file.

Notification

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

Download schema: notification-schema.json, create-update-notification-schema.json

Sample GET request:

{
    "notificationId": 25056,
    "notificationTitle": "Notification for 1-ABCDEF",
    "creationDate": "2020-12-09T08:30:14Z",
    "modificationDate": "2020-12-09T08:30:14Z",
    "notificationStatus": "ACTIVE",
    "emails": [
        "user@example.com"
    ],
    "contracts": [
        "1-ABCDEF"
    ]
}

Sample POST request:

{
    "notificationTitle": "Notification for 1-ABCDEF",
    "notificationStatus": "ACTIVE",
    "emails": [
        "user@example.com"
    ],
    "contracts": [
        "1-ABCDEF"
    ]
}

Sample PUT request:

{
    "notificationTitle": "Notification for 1-ABCDEF",
    "notificationStatus": "ACTIVE",
    "emails": [
        "user@example.com"
    ],
    "contracts": [
        "1-ABCDEF"
    ]
}

Notification members

Member Type GET POST PUT Description
Notification: Specifies a set of people to notify whenever an invoice is available for a set of contracts.
contracts Array The contracts for which the notification applies.
creationDate String The ISO 8601 timestamp of the notification’s creation.
emails Array The recipients’ email addresses.
modificationDate String The ISO 8601 timestamp of the notification’s most recent change.
notificationId Integer Identifies the notification.
notificationStatus Enumeration Either ACTIVE to notify recipients about changes to invoices, or SUSPENDED to disable a notification.
notificationTitle String The title of the notification.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

If any error occurs, this API responds with JSON objects that follow the HTTP Problem Details standard. This example shows an error response object, where the title is a descriptive label for the overall problem, and the incidentId may be useful if you need to communicate the problem to your Akamai representative. It also includes the errors array that lists problems detected in the request.

{
    "type": "/billing/error-types/1",
    "title": "An incorrect request has been sent",
    "incidentId": "82ea2b60-a0c8-425f-9300-85bb3185cdf2",
    "errors": [
      {
        "type": "/billing/error-types/2",
        "title": "Field 'from' is invalid. Incorrect value: null"
      }
    ]
}

HTTP status codes

This section lists the full range of response codes the API may generate.

Code Description
200 The operation succeeded.
204 No Content. There is no data that matches your request.
400 Bad Request. This typically occurs due to a problem with the format of request data, such as an non-parsing or invalid body of data, or an invalid set of query parameters or values.
401 API authentication failure. See Get started for guidance on how to correctly set up your API hostname token.
403 No permission to access this resource. This most likely reflects a limitation on the identity of the Control Panel user corresponding to the API client. See Get started to make sure you have permission to access all the functionality you need.
404 Resource not found. This typically occurs when a resource keyed by a URL path parameter no longer exists, or if the request URL is garbled in some other way.
429 Too many requests. See Rate limiting for more information.
500 Internal server error.