Billing (V1)

Billing API allows a user with Billing & Payments permission to get all their permitted billing accounts information and download specific invoices.

To retrieve your invoice or credit memo details, refer to Billing (V2) in the API Reference section.

To download your billing document, refer to Download invoice document under the Getting Started section. All other methods can be found below.

GET Accounts

GET /finance/accounts
Method GET
URL or End Point /v1/finance/accounts
Headers Authorization, Content-Type
Query Parameters offset, limit, sorts
Body Not applicable

The Get finance accounts API returns a summary of all accounts that the user has billing and invoice retrieval access to. This can only be done under a user with 'Billing & Payments' permission. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshots show a sample curl request and JSON response for this API. The request indicates that the response should be sorted by account number, and limited to two accounts per page starting from offset '0'. The response shows that the user has access to a total of 11 accounts, with 2 displayed in the response.

Copy 
curl -X
GET "https://api.equinix.com/v1/finance/accounts?offset=0&limit=2&sorts=ACCOUNT_NUMBER"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

The description of the query parameter is as follows:

Query Parameter name Mandatory Type Example Applicable Values Description
offset No integer 0

The starting index of the returned response.

E.g. If '0', the first account returned would be account number 1 from the search results.
If '1', the first account returned would be account number 2 from the search results.

Default value: 0.
limit No integer 2

The maximum number of search results to be shown per page.

Default value: 10.
Minimum value: 1.
Maximum value: 100.
sorts No integer ACCOUNT_NUMBER ACCOUNT_NUMBER,
PARENT_ACCOUNT_NUMBER,
ACCOUNT_NAME,
-ACCOUNT_NUMBER,
-PARENT_ACCOUNT_NUMBER,
-ACCOUNT_NAME

The billing summary can be sorted by account number, parent account number, or account name in ascending or descending order.

To sort by descending order, the applicable value must start with a '-'.

Default value: ACCOUNT_NUMBER.
Copy 
{
    "data": [
        {
        "accountNumber": "007",
        "parentAccountNumber": "101230",
        "accountName": "JOHN DOE CORPORATION",
        "accountIbxs": [
            "CH1",
            "SV4"
        ]
        },
        {
        "accountNumber": "1234",
        "parentAccountNumber": "101230",
        "accountName": "JOHN DOE LIMITED",
        "accountIbxs": [
            "DC3"
        ]
        }
    ],
    "page": {
        "total": 11,
        "limit": 2,
        "offset": 0,
        "sorts": [
        "ACCOUNT_NUMBER"
        ]
    },
    "_links": {
        "prev": {
        "href": "/accounts?limit=2&offset=0&sorts=ACCOUNT_NUMBER"
        },
        "self": {
        "href": "/accounts?limit=2&offset=0&sorts=ACCOUNT_NUMBER"
        },
        "next": {
            "href": "/accounts?limit=2&offset=2&sorts=ACCOUNT_NUMBER"
        }
    }
}

The description of the response payload is as follows:

Field name Type Example Description
data array[objects] Data list of summarized account information.
accountNumber string 007

The customer account number.

This is the same account number tied to the cage of the IBX.

This number is important if you want to request for a billing summary for this account, or if you want to download a specific invoice document for this account.

parentAccountNumber string 101230 The primary 'parent' account number that the customer account number belongs to.

This number is important if you want to request for a billing summary for this parent account or if you want to download a specific invoice document for this account.

accountName string JOHN DOE CORPORATION

The customer account name.

This is the same account name tied to the cage of the IBX.
accountIbxs array[strings] CH1,
SV4		 The IBX location codes linked to this customer account.
page object Page information.
total integer 11 The total number of customer accounts that the user has permissions to view billing history.
limit integer 2

The number of customer accounts to be returned per page.

This is the same limit set in the query parameters.
offset integer 0

The starting index of the returned response.

This is the same offset set in the query parameter.
sorts array [string] ACCOUNT_NUMBER

The sorting preference of results.

This is the same sorting preference set in the query parameter.
_links object Links that show the previous page, current page, and next page of search results.
prev object Previous search results page.
href string /accounts?limit=2&offset=0& sorts=ACCOUNT_NUMBER Link to the previous page of search results.
self object Current search results page. This is a self-reference.
href string /accounts?limit=2&offset=0& sorts=ACCOUNT_NUMBER Link to the current page of search results.
next object Next search results page.
href string /accounts?limit=2&offset=2& sorts=ACCOUNT_NUMBER Link to the next page of search results.

If you get “Insufficient permissions” error, contact your Master Administrator.

GET Accounts {accountNumber}

GET /accounts/{accountNumber}
Method GET
URL or End Point /v1/finance/accounts/{accountNumber}
Headers Authorization, Content-Type
Query Parameters months
Body Not applicable

The Get accounts {accountNumber} API returns billing summary for a specific account number. This can only be done under a user with 'Billing & Payments' permission for this specific account number. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshots show a sample curl request and JSON response for this API. The request shows a search for the July 2019 billing summary for the account number, 123321. The response returns the invoice, payment, and billing information.

Copy 
curl -X
GET
"https://api.equinix.com/v1/finance/accounts/123321?months=2019-07-01"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

The description of the URL parameters is as follows:

URL Parameter name Mandatory Type Example Description
accountNumber Yes string 123321 The specific account number for which to retrieve the billing summary. This is the account number associated with the account or parent account.

If you are not sure of the accountNumber, refer to Get Accounts under the API Reference section.

The description of the query parameter is as follows:

Query Parameter name Mandatory Type Example Description
months No array[string] 2019-07-01

The month(s) to retrieve billings.

Provide a date in the ISO_LOCAL_DATE format: yyyy-MM-dd

Billings can only be retrieved up to a year before the current month. Eg. If the current month is September 2019, billings can only be retrieved from August 2019 (2019-08-01) to October 2018 (2018-10-01).

Multiple dates should be comma-separated. Eg. To retrieve August and July 2019 billings, input '2019-08-01,2019-07-01'.

Default value: The past 12 months from the date of this request.
Copy 
{
    "accountNumber": "123321",
    "billingFrequency": "MONTHLY",
    "currencyCode": "USD",
    "invoiceLanguage": "English",
    "invoiceFormat": "PDF",
    "invoices": [
      {
        "invoiceId": "654321879",
        "transactionNumber": "654321879",
        "amount": 49793.32,
        "date": "2019-07-01",
        "invoiceLanguage": "English",
        "type": "INVOICE",
        "documents": [
          {
            "documentId": "DETAILED_PDF_EN",
            "fileType": "PDF_DETAILS",
            "type": "INVOICE"
          },
          {
            "documentId": "DETAILED_XLS_EN",
            "fileType": "EXCEL_DETAILS",
            "type": "INVOICE"
          },
          {
            "documentId": "SUMMARY_PDF_EN",
            "fileType": "PDF_SUMMARY",
            "type": "INVOICE"
          },
          {
            "documentId": "SUMMARY_XLS_EN",
            "fileType": "EXCEL_SUMMARY",
            "type": "INVOICE"
          }
         ]
      },
      {
        "invoiceId": "654321880",
        "transactionNumber": "654321879",
        "amount": -13.12,
        "date": "2019-07-01",
        "invoiceLanguage": "English",
        "type": "CREDIT_MEMO",
        "documents": [
          {
            "documentId": "DETAILED_PDF_EN",
            "fileType": "PDF_DETAILS",
            "type": "CREDIT_MEMO"
          },
          {
            "documentId": "DETAILED_XLS_EN",
            "fileType": "EXCEL_DETAILS",
            "type": "CREDIT_MEMO"
          },
          {
            "documentId": "SUMMARY_PDF_EN",
            "fileType": "PDF_SUMMARY",
            "type": "CREDIT_MEMO"
          },
          {
            "documentId": "SUMMARY_XLS_EN",
            "fileType": "EXCEL_SUMMARY",
            "type": "CREDIT_MEMO"
          }
        ]
      }
    ],
    "payments": [
     {
        "paymentId": "FRT0554400011122",
        "date": "2019-07-05",
        "status": "UNAPPLIED",
        "amount": 0
     },
     {
        "paymentId": "FRT0554400011144",
        "date": "2019-07-05",
        "status": "APPLIED",
        "amount": 58658.09
      }
    ],
    "billingContact": {
        "firstName": "Natasha",
        "lastName": "Huang",
        "email": "nhuang@company.com"
    }
}

The description of the response payload is as follows:

Field name Type Example Description
accountNumber string 123321

The customer account number.

This is the same account number tied to the cage of the IBX.
billingFrequency string MONTHLY

The frequency of billing.

Billing frequency - Description
MONTHLY - Billing is scheduled on a monthly basis.
QUARTERLY - Billing is scheduled on a quarterly basis (January- March, April- June, July- September, October- December).
ANNUALLY - Billing is scheduled on a yearly basis (January - December).
currencyCode string USD The currency code of the account.
invoiceLanguage string English The language that the invoice was generated in.
invoiceFormat string PDF

Format of the invoice.

Invoice formats - Description
PDF - Invoice is in PDF format.
EXCEL - Invoice is in Excel format.
invoices array[objects] Available invoices for the account, and its corresponding information that consists of invoice ID number, transaction number, total amount of invoice, date of invoice, invoicing language, invoice type, and its document information.
invoiceId string 654321879

Invoice identification (ID) number.

The ID is exactly the same as invoice transaction number.

This number is important if you want to download a specific invoice document.

transactionNumber string 654321879 Transaction number linked to the invoice.
amount number 49793.32 Total amount of the invoice.
date string 2019-07-01 Date the invoice was issued.
invoiceLanguage string English Language invoice is issued in.
type string INVOICE

Type of invoice issued by Equinix.

Types of invoice - Description
INVOICE - An invoice issued as scheduled.
MANUAL_INVOICE - An invoice issued manually.
CREDIT_MEMO - A credit memo.
STATEMENT - A statement of accounts.
documents array[objects] Invoice documents information the invoice that consists of document ID, file type, and document type.
documentId string DETAILED_PDF_EN

Document ID.

The is a combination of internal file type and language code (LC) or (NA) where no specific language is associated with the document. Each combination should be unique within a transaction.

Document ID - Description
DETAILED_PDF_(LC) - English detailed doc in PDF format.
DETAILED_XLS_(LC) - English detailed doc in Excel format.
SUMMARY_PDF_(LC) - English summary doc in PDF format.
SUMMARY_XLS_(LC) - English summary doc in Excel format.
Government documents
BOLETO_PDF_NA - A PDF payment slip issued by a federal institution for Equinix invoices, common in Brazil and some Latin American countries.
OFFICIAL_INVOICE_PDF_NA - A PDF billing invoice issued by a federal institution, used by Equinix in countries like Brazil and Turkey.
NF_URL_NA - A Nota Fiscal (NF) is an official tax document provided to Equinix as a URL, unique to Brazil and some Latin American countries like Mexico, e.g., http://www.documentUrlhere.com.

This ID is important if you want to download a specific invoice document.

fileType string PDF_DETAILS

File type of document.

File types - Description
PDF_DETAILS - Detailed document in PDF format.
EXCEL_DETAILS - Detailed document in Excel format.
PDF_SUMMARY - Summary document in PDF format.
EXCEL_SUMMARY - Summary document in Excel format.
Government documents
BOLETO_PDF - A payment slip in PDF format.
INVOICE_PDF - A billing invoice in PDF format.
NF_URL - A web link (URL) to access electronic invoice in PDF format.
type string INVOICE

Type of invoice document issued by Equinix.

File types - Description
INVOICE - An invoice issued as scheduled.
MANUAL_INVOICE - An invoice issued manually.
CREDIT_MEMO - A credit memo.
STATEMENT - A statement of accounts.
payments array[objects] Payments information that consists of payment ID, date of payment, status of payment, and amount of payment.
paymentId string FRT0554400011122

Payment ID number.

This is payment receipt number.
date string 2019-07-05

Date the payment was received.

This does not indicate if the payment was applied to the invoice.
status string UNAPPLIED

Status of the payment received. This indicates if the payment was applied to the invoice.

Payment status - Description
APPLIED - Payment was received and applied to the invoice.
UNAPPLIED - Payment was received but not applied to the invoice.
amount string 0 Payment amount applied to the account.
billingContact object Billing contact information that consists of the first and last names of the billing contact and their email address.
firstName string Natasha First name of billing contact.
lastName string Huang Last name of billing contact.
email string nhuang@company.com Email address of billing contact.

If you get “Insufficient permissions” error, contact your Master Administrator.