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.

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.

Query Parameter name

Mandatory

Type

Example

Applicable Values

Description

offset

integer

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

integer

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

Default value: 10.
Minimum value: 1.
Maximum value: 100.

sorts

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.

{
  "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.

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.

Query Parameter name

Mandatory

Type

Example

Description

months

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.

{
  "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.

GET Accounts​

GET Accounts {accountNumber}​

GET Accounts

GET Accounts {accountNumber}