Skip to main content
Index

Billing (V2)

Billing (V2) API allows a user with billing & payments permission to get all their permitted billing document summaries and details.

GET Invoices

GET /invoices

 Method  GET
 URL or End Point  /v2/invoices
 Headers  Authorization, Content-Type
 Query Parameters    startDate, endDate, accountNumbers, transactionIds, offset, limit
 Body  Not applicable

 

This method retrieves a summary of billing documents based on the search criteria passed, and the authenticated user's billing and payments permission. Only invoices and credit memos from the past 365 days may be retrieved. 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.

 

Currently, we support the retrieval of billing documents for all regions (APAC, AMER, EMEA) except Brazil. To retrieve your billing information for Brazil, refer to the Equinix Customer Portal

 

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 sample curl requests for different scenarios, and a successful JSON response for this method. 

 

Search by dates and account numbers

curl -X

GET "https://api.equinix.com/v2/invoices?startDate=2020-12-01&endDate=2021-02-28&accountNumbers=3456,789101&offset=1&limit=1"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Search by transaction identifiers (IDs)

curl -X

GET "https://api.equinix.com/v2/invoices?transactionIds=112233445566,123456789123&offset=1&limit=1"

-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
startDate No string 2020-12-01  

Start date of search. 

 

Format: YYYY-MM-DD. 

 

Earliest permitted date: 365 days before today.

Default date: 30 days before today (when startDate and endDate are not provided).

Default date range: 30 days between startDate and endDate .

Date range: 1 to 90 days between startDate and endDate.

endDate No string 2021-02-01  

End date of search.

 

Format: YYYY-MM-DD. 

 

Default date: today (when startDate and endDate are not provided).

Default date range: 30 days between startDate and endDate.

Date range: 1 to 90 days between startDate and endDate.

accountNumbers No array
[strings]

3456,

789101

 

Account numbers associated with invoices and credit memos. Multiple account numbers should be comma-separated.
 

Default value: All user's permitted account numbers. 

transactionIds No

array

[strings]

112233445566,

123456780003

 

Transaction IDs of billing documents, such as invoice or credit memo numbers. Multiple transactions IDs should be comma-separated.

Only invoices and credit memos from the past 365 days (1 year) will be returned. 

 

Default value: All invoices for user's permitted accounts within the date range. 

offset No integer 1  

Defines the index of the first item returned in the response. By specifying the offset, the response returns a subset of records starting with the offset value.

 

For example, if the offset is 10, the starting item returned in the response would be the 11th item. 

 

Default value: 0.

limit No integer 1  

Defines the maximum number of items returned per page. 

 

Default value: 10.

 

Limit: 1 to 200.

 

When returning details for multiple billing documents, the data returned is from earliest document to most recent document.

 

{
  "data": [
    {
      "transactionId": "112233445566",
      "transactionType": "INVOICE",
      "transactionDate": "2021-12-01",
      "businessLegalEntity": "Equinix (UK) Ltd",
      "customerDetails": {
        "accountName": "John Doe Corporation",
        "accountNumber": "3456",
        "accountContact": "Attn: Accounts Payable PO 123ABC",
        "address": {
          "addressLine1": "10 Corporation Lane",
          "addressLine2": "#100",
          "city": "Slough",
          "state": "Berkshire",
          "countryCode": "UK",
          "zipCode": "SL1 ABC"
        },
        "region": "EMEA"
      },
      "billingCycle": "1st of the month",
      "billingContacts": {
        "firstName": "JOHN",
        "lastName": "DOE",
        "details": [
          {
            "type": "PHONE",
            "value": "+44 111 222 3333"
          }
        ]
      },
      "paymentDueDate": "2021-03-02",
      "paymentTerms": "Net 60",
      "currencyCode": "GBP",
      "totalRecurringAmount": 600,
      "totalNonRecurringAmount": 0,
      "totalAmount": 150,
      "totalAdjustment": 0,
      "vatNumber": "GB12345789",
      "paymentInstructions": {
        "electronic": {
          "bankName": "Example Bank",
          "bankAddress": {
            "addressLine1": "123 Bank Lane",
            "addressLine2": "Berkshire, SL1 ABC"
          },
          "payeeName": "Equinix (UK) Ltd",
          "payeeAccountNumber": "9876543210",
          "bankCode": "GB11AAAA1234569876543210",
          "swiftCode": "AAAAGBCC123",
          "sortCode": "123456"
        },
        "check": {
          "bankName": "Example Bank",
          "bankAddress": {
            "addressLine1": "123 Bank Lane",
            "addressLine2": "Berkshire, SL1 ABC"
          },
          "emailRemittance": "example@equinix.com"
        },
        "taxInfo": [
          {
            "description": " at 20% on 600",
            "value": "120"
          }
        ]
      }
    }
  ],
  "pagination": {
    "offset": 1,
    "limit": 1,
    "total": 212,
    "next": "/invoices?startDate=2020-12-01&endDate=2021-02-28&accountNumbers=3456,789101&limit=1&offset=2",
    "previous": "/invoices?startDate=2020-12-01&endDate=2021-02-28&accountNumbers=3456,789101&limit=1&offset=0"
  }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
data

array

[objects]

  Data returned from your query. Each billing document object comprises the following fields where applicable: transactionId, transactionType, transactionDate, businessLegalEntity, customerDetails, billingCycle, billingContacts, paymentDueDate, paymentTerms, currencyCode, totalRecurringAmount, totalNonRecurringAmount, totalAmount, totalAdjustment, vatNumber, paymentInstructions, taxInfo.
transactionId string 112233445566 Transaction ID of the billing document.
transactionType string INVOICE

Type of billing transaction. 

The billing document returned can be an INVOICE or CREDIT_MEMO.

transactionDate string 2021-12-01

Date the billing document was issued.


Format: YYYY-MM-DD.

businessLegalEntity string Equinix (UK) Ltd Name of the Equinix entity that issued the billing document. 
customerDetails object  

Details of the the customer account that receives this document. This object comprises the following fields where applicable: accountName, accountNumber, accountContact, address, region.

accountName string John Doe Corporation Customer account name. 
accountNumber string 3456

Customer account number.

accountContact string Attn: Accounts Payable PO 123ABC Customer billing contact person. 
address object   Customer address. This object comprises the following fields where applicable: addressLine1, addressLine2, city, state, countryCode, zipCode.
addressLine1 string 10 Corporation Lane Line 1 of the customer address. 

For example, this could be a street, PO Box, or company name.
addressLine2 string #100

Line 2 of the customer address. 

 

For example, this could be a unit, or building.

city string Slough City, district, suburb, town, or village.
state string Berkshire State, county, province, or region.
countryCode string UK

Country code.

 

Format: ISO-3166 ALPHA-2 code 

 

For a full list of country codes, refer to Country Codes in the Appendix.

zipCode string SL1 ABC

Postal code or ZIP code.

region string EMEA

Regional code representing the region where the customer is located.
 

Region - Description

AMER - North America and South America

EMEA - Europe, Middle East, and Africa

APAC - Asia-Pacific 

billingCycle string 1st of the month Date when billing cycle begins.
billingContacts object   Equinix billing contact and their details. This object comprises the following fields where applicable: firstName, lastName, details.
firstName string JOHN First name of Equinix billing contact.
lastName string DOE Last name of Equinix billing contact.
details

array

[objects]

  Contact details. Each object comprises the following fields: type, value.
type string PHONE

Contact detail type in a type-value pair.

 

This could be EMAIL, MOBILE, or PHONE contact information. 

value string +44 111 222 3333 Value related to type in the type-value pair.
paymentDueDate string 2021-03-02

Date the payment is due. 

 

Format: YYYY-MM-DD

paymentTerms string Net 60 Payment terms. 
currencyCode string GBP

Country code.

 

Format: ISO 4217 Currency Code

 

For a full list of currency codes, see Currency Codes in the Appendix.

totalRecurringAmount number 600 Total recurring charges.
totalNonRecurringAmount number 0 Total non-recurring charges.
totalAmount number 150 Total charges. This includes both recurring and non-recurring charges. 
totalAdjustment number 0 Total amount adjusted.
vatNumber string GB12345789 Customer value added tax (VAT) identification number. 
paymentInstructions object   Payment instructions for electronic and check payments. This object comprises the following fields where applicable: electronic, check, emailRemittance.
electronic object   Electronic payment instructions. This object comprises the following fields where applicable: bankName, bankAddress, payeeName, payeeAccountNumber, bankCode, swiftCode, sortCode.
bankName string Example Bank Name of bank for electronic payment. 
bankAddress object   Bank address. 
addressLine1 string 123 Bank Lane Line 1 of the bank address.
addressLine2 string Berkshire, SL1 ABC Line 2 of the bank address.
payeeName string Equinix (UK) Ltd Equinix payee name for electronic payment.
payeeAccountNumber string 9876543210 Equinix payee account number. 
bankCode string GB11AAAA1234569876543210

Equinix international bank account number in accordance with the applicable bank code of the region. 

 

For example, this could be ABA, BSB, CNAPS, or IBAN. For more information, refer to Bank Codes in the Appendix. 

swiftCode string AAAAGBCC123 Equinix SWIFT/BIC identifier. 
sortCode string 123456 Equinix sort code. 
check object   Check payment instructions. This object comprises the following fields where applicable: bankName, bankAddress.
bankName string Example Bank Name of bank for check payment.
bankAddress object   Bank address.
addressLine1 string 123 Bank Lane Line 1 of the bank address.
addressLine2 string Berkshire, SL1 ABC Line 2 of the bank address.
emailRemittance string example@equinix.com Equinix email address to send remittance advice. 
taxInfo

array

[objects]

  Applicable taxes. 
description string at 20% on 600 Description of taxes applied to this invoice.
value string 120 Total value of the applied tax. 
pagination object   Page information. This object comprises the following fields: offset, limit, total, next, previous.
offset integer 1

Offset of the first item in the response, as defined in the query parameter 'offset'.

limit integer 1

Maximum number of items in the response, as defined in the query parameter 'limit'.

total integer 212

Total number of available items in the record.

next string /invoices?startDate=2020-12-01&endDate=2021-02-28&accountNumbers=3456,789101&limit=1&offset=2 URL for the next page of results.
previous string  /invoices?startDate=2020-12-01&endDate=2021-02-28&accountNumbers=3456,789101&limit=1&offset=0 URL for the previous page of results.

 

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

GET Invoices Details

GET /invoices/details

 Method  GET
 URL or End Point  /v2/invoices/details
 Headers  Authorization, Content-Type
 Query Parameters    startDate, endDate, accountNumbers, transactionIds, offset, limit
 Body  Not applicable

 

This method retrieves the details of billing documents based on the search criteria passed, and the authenticated user's billing and payments permission. Only invoices and credit memos from the past 365 days may be retrieved. 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.

 

Currently, we support the retrieval of billing documents for all regions (APAC, AMER, EMEA) except Brazil. To retrieve your billing information for Brazil, refer to the Equinix Customer Portal

 

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 sample curl requests for different scenarios, and a successful JSON response for this method. 

 

Search by dates and account numbers

curl -X

GET "https://api.equinix.com/v2/invoices/details?startDate=2020-12-01&endDate=2021-02-28&accountNumbers=3456,789101&offset=1&limit=1"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Search by transaction identifiers (IDs)

curl -X

GET "https://api.equinix.com/v2/invoices/details?transactionIds=112233445566,123456789123&offset=1&limit=1"

-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
startDate No string 2020-12-01  

Start date of search. 

 

Format: YYYY-MM-DD. 


Earliest permitted date: 365 days before today

Default date: 30 days before today (when startDate and endDate are not provided)

Default date range: 30 days between startDate and endDate 

Date range: 1 to 90 days between startDate and endDate

endDate No string 2021-02-01  

End date of search.

 

Format: YYYY-MM-DD. 

 

Default date: today (when startDate and endDate are not provided)

Default date range: 30 days between startDate and endDate

Date range: 1 to 90 days between startDate and endDate 

accountNumbers No array
[strings]

3456,

789101

 

Customer account numbers associated with invoices and credit memos. Multiple account numbers should be comma-separated.
 

Default value: All user's permitted account numbers. 

transactionIds No

array

[strings]

112233445566,

123456780003

 

Transaction IDs of billing documents, such as invoice or credit memo numbers. Multiple transactions IDs should be comma-separated.

Only invoices and credit memos from the past 365 days (1 year) will be returned. 

 

Default value: All invoices for user's permitted accounts within the date range. 

offset No integer 1  

Defines the index of the first item returned in the response. By specifying the offset, the response returns a subset of records starting with the offset value.

 

For example, if the offset is 10, the starting item returned in the response would be the 11th item. 

 

Default value: 0.

limit No integer 1  

Defines the maximum number of items returned per page. 

 

Default value: 10.

 

Limit: 1 to 200.

 

{
  "data": [
    {
      "transactionId": "112233445566",
      "businessLegalEntity": "Equinix (UK) Ltd",
      "transactionType": "INVOICE",
      "transactionDate": "2021-01-01",
      "orderId": "1-202345678910",
      "lineNumber": "1",
      "subLineNumber": "2",
      "customerDetails": {
        "accountName": "John Doe Corporation",
        "accountNumber": "3456",
        "legalEntity": "JOHN DOE CORPORATION",
        "region": "EMEA",
        "countryCode": "UK"
      },

      "purchaseOrderNumber": "EQX-1000000000",
      "billingAgreementId": "1-30000000000",

      "customerReferenceId": "ABC-1-30000000000",

      "priorAdjustmentReference": "1-20000000000",
      "ibxs": [
        "LD6"
      ],
      "contacts": [
        {
          "firstName": "JANE",
          "lastName": "SMITH",
          "type": "BOOKED_BY"
        },
        {
          "firstName": "RICHARD",
          "lastName": "ROE",
          "type": "BILLING_ANALYST"
        }
      ],
      "orderBookedDate": "2015-01-01",
      "activityType": "RECURRING_CHARGE",
      "productCategory": "Interconnection",
      "productDescription": "Cross Connect- Single-Mode Fiber",
      "productCode": "CC00001",
      "detailedDescription": "Location: 00000 S/N: 1111111-A EQUINIX",
      "ibxDescription": "London IBX - LD6",
      "quantity": 1,
      "unitOfMeasure": "EA",
      "unitPrice": 100,
      "frequency": "MONTHLY",
      "currencyCode": "USD",
      "localCurrencyCode": "GBP",
      "exchangeRate": 0.749345,
      "nonRecurringAmount": 0,
      "recurringAmount": 100,
      "adjustment": 0,
      "taxAmount": 0,
      "totalAmount": 100,
      "legacyOrderId": "1-2000000000000",
      "additionalInfo": [
        {
          "key": "SERIAL_NUMBER",
          "value": "1111111-A"
        },
        {
          "key": "Z_SIDE_CUSTOMER_NAME",
          "value": "EQUINIX"
        }
      ]
    }
  ],
  "pagination": {
    "offset": 1,
    "limit": 1,
    "total": 506,
    "next": "/invoices/details?startDate=2020-12-01&endDate=2021-02-28&accountNumbers=3456,789101&limit=1&offset=2",
    "previous": "/invoices/details?startDate=2020-12-01&endDate=2021-02-28&accountNumbers=3456,789101&limit=1&offset=0"
  }
}

 

The description of the response payload is as follows:

 

Field name Type Example Description
data

array

[objects]

  Data returned from your query. Each object represents one line item in a billing document, and it comprises the following fields where applicable: transactionId, businessLegalEntity, transactionType, transactionDate, orderId, lineNumber, subLineNumber, customerDetails, billingAgreementId, ibxs, contacts, orderBookedDate, activityType, productCategory, productDescription, productCode, detailedDescription, ibxDescription, quantity, unitOfMeasure, unitPrice, frequency, currencyCode, localCurrencyCode, nonRecurringAmount, recurringAmount, adjustment, taxAmount, totalAmount, legacyOrderId, additionalInfo.
transactionId string 112233445566 Transaction ID of the associated billing document.
businessLegalEntity string Equinix (UK) Ltd Name of the Equinix entity that issued the billing document.
transactionType string INVOICE

Type of billing transaction. 

The billing document returned can be an INVOICE or CREDIT_MEMO.

transactionDate string 2021-01-01

Date the billing document was issued.


Format: YYYY-MM-DD

orderId string 1-202345678910 Order ID or order number associated with this line item.
lineNumber string 1 Billing document line number.
subLineNumber string 2

Billing document line sub-line number. 

 

The lineNumber and subLineNumber together represents one line item number on your billing document. For example, when lineNumber is 1 and subLineNumber is 1, it represents the first line item number in your document. Subsequently, when lineNumber is 1 and subLineNumber is 2, it represents the next line item (line item 1.2) in your document. 

customerDetails object  

Details of the the customer account associated with this line item. This object comprises the following fields where applicable: accountName, accountNumber, legalEntity, region, countryCode.

accountName string John Doe Corporation Customer account name. 
accountNumber string 3456

Customer account number.

legalEntity string JOHN DOE CORPORATION Customer legal entity name.
region string EMEA

Regional code representing the region where the customer is located.


Region - Description

AMER - North America and South America

EMEA - Europe, Middle East, and Africa

APAC - Asia-Pacific 

countryCode string UK

Country code.

 

Format: ISO-3166 ALPHA-2 code 

 

For a full list of country codes, refer to Country Codes in the Appendix.

purchaseOrderNumber string EQX-1000000000 Associated purchase order number.
billingAgreementId string 1-30000000000 Billing agreement number.
customerReferenceId string ABC-1-30000000000 Customer's own reference ID.
priorAdjustmentReference string 1-20000000000 Associated prior invoice or credit memo ID subject to adjustment.
ibxs

array

[strings]

LD6

IBX location codes representing the IBX data centers associated with this line item. 

 

For example, LD6 represents an IBX in London, England.

recurringStartDate string  

Start date of the recurring amount, if applicable.

 

Format: YYYY-MM-DD

recurringEndDate string  

End date of the recurring amount, if applicable. 

 

Format: YYYY-MM-DD

contacts

array

[objects]

  Contact persons associated with this line item. Each object comprises the following fields where applicable: firstName, lastName, type.
firstName string JANE First name of contact person.
lastName string SMITH Last name of contact person.
type string BOOKED_BY

Contact person type.

 

Type - Description

BOOKED_BY - Customer ordering contact. 

BILLING_ANALYST - Equinix billing contact. 

orderBookedDate string 2015-01-01

Date the order was booked.

 

Format: YYYY-MM-DD

activityType string RECURRING_CHARGE

Type of transaction charge.

 

Activity type - Description
CREDIT_MRC - Monthly recurring credit charge.

CREDIT_NRC - Non-recurring credit charge.

ONE_TIME_CHARGE - One time or ad-hoc charge.

RECURRING_CHARGE - Recurring charge.

PRIOR_RECURRING_CHARGE - Prior recurring charge.

ADJUSTMENT_CHARGE - Adjusted charge.

productCategory string Interconnection Name of Equinix product category.
productDescription string Cross Connect- Single-Mode Fiber Brief description of the Equinix product or service.
productCode string CC00001 Equinix product code.
detailedDescription string Location: 00000 S/N: 1111111-A EQUINIX Detailed description of the Equinix product or service.
ibxDescription string London IBX - LD6 Description of the IBX data center associated with this line item.
quantity integer 1 Numerical quantity of the product or service associated with unitOfMeasure.
unitOfMeasure string EA

Unit of measurement associated with quantity.

 

For example, when a product or service has quantity 1 and unitOfMeasure EACH, there is only 1 piece of it. When a product or service has quantity 1 and unitOfMeasure KVA, there is 1 kilo-volt-ampere of it.

unitPrice number 100 Price per unit of this product or service. 
frequency string MONTHLY

Frequency of the recurring charge. 

 

Frequency - Description
MONTHLY - Charge occurs every month.

QUARTERLY - Charge occurs every 3 months. 

YEARLY - Charge occurs every 12 months.

currencyCode string USD

Currency code representing the billing document currency. This currency applies to the values in the following fields: nonRecurringAmount, recurringAmount, adjustment, taxAmount, totalAmount.

 

Format: ISO 4217 Currency Code.

 

For a full list of currency codes, see Currency Codes in the Appendix.

localCurrencyCode string GBP

Currency code representing the local currency.

 

Refer to field 'currencyCode' for more information.

exchangeRate number 0.749345

Applied foreign exchange conversion rate from currencyCode to localCurrencyCode.

 

For example, the exchange rate from USD to GBP at 0.749345 has been applied.

nonRecurringAmount number 0 Non-recurring charge.
recurringAmount number 100 Recurring charge.
adjustment number 0 Applicable adjustments or discounts.
taxAmount number 0 Applicable tax charge.
totalAmount number 100 Net total charge after applicable adjustments and taxes.
legacyOrderId string 1-2000000000000 Associated order ID or order number from legacy systems.
additionalInfo

array

[objects]

 

List of any additional details or information related to this item line. Each object comprises the following fields: key, value.

key string SERIAL_NUMBER Name of the detail in the key-value pair.
value string 1111111-A Value of associated detail in the key-value pair.
pagination object   Page information. This object comprises the following fields: offset, limit, total, next, previous.
offset integer 1

Offset of the first item in the response, as defined in the query parameter 'offset'.

limit integer 1

Maximum number of items in the response, as defined in the query parameter 'limit'.

total integer 212

Total number of available items in the record.

next string /invoices?startDate=2020-12-01&endDate=2021-02-28&accountNumbers=3456,789101&limit=1&offset=2 URL for the next page of results.
previous string  /invoices?startDate=2020-12-01&endDate=2021-02-28&accountNumbers=3456,789101&limit=1&offset=0 URL for the previous page of results.

 

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