Skip to main content
Index

Billing

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

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 Started 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.

 

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

 

{
  "accountNumber": "123321",
  "billingFrequency": "MONTHLY",
  "currencyCode": "USD",
  "invoiceLanguage": "English",
  "invoiceFormat": "PDF",
  "invoices": [
    {
      "invoiceId": "2bbd6f8c-c46d-36g9-a76a-1234567890e1",
      "transactionNumber": "100210112345",
      "amount": 49793.32,
      "date": "2019-07-01",
      "invoiceLanguage": "English",
      "type": "INVOICE",
      "documents": [
        {
          "documentId": "15112345",
          "fileType": "PDF_DETAILS",
          "type": "INVOICE"
        },
        {
          "documentId": "15123423",
          "fileType": "EXCEL_DETAILS",
          "type": "INVOICE"
        },
        {
          "documentId": "15123154",
          "fileType": "PDF_SUMMARY",
          "type": "INVOICE"
        },
        {
          "documentId": "15123457",
          "fileType": "EXCEL_SUMMARY",
          "type": "INVOICE"
        }
      ]
    },
    {
      "invoiceId": "2bbd6f8c-c46d-36g9-a76a-1234567890e2",
      "transactionNumber": "100210112349",
      "amount": -13.12,
      "date": "2019-07-01",
      "invoiceLanguage": "English",
      "type": "CREDIT_MEMO",
      "documents": [
        {
          "documentId": "11232583",
          "fileType": "PDF_DETAILS",
          "type": "CREDIT_MEMO"
        },
        {
          "documentId": "15112346",
          "fileType": "EXCEL_DETAILS",
          "type": "CREDIT_MEMO"
        },
        {
          "documentId": "11234513",
          "fileType": "PDF_SUMMARY",
          "type": "CREDIT_MEMO"
        },
        {
          "documentId": "15123454",
          "fileType": "EXCEL_SUMMARY",
          "type": "CREDIT_MEMO"
        }
      ]
    }
  ],
  "payments": [
    {
      "paymentId": "2345459_Unapplied",
      "date": "2019-07-05",
      "status": "UNAPPLIED",
      "amount": 0
    },
    {
      "paymentId": "2123459_Applied",
      "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

2bbd6f8c-c46d-36g9-a76a-

1234567890e1

Invoice identification (ID) number. 

 

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

transactionNumber string 100210112345

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 15112345

Document ID number.

 

This number 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.

type string INVOICE

Type of invoice document issued by Equinix.

 

This matches the type of invoice.

payments array[objects]   Payments information that consists of payment ID, date of payment, status of payment, and amount of payment. 
paymentId string 2345459_Unapplied

Payment ID number.

 

This is a combination of a payment number and payment status.

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.