Orders (V2 Beta)

Orders APIs allow an authenticated user with the required permissions to do the following: retrieve order details; retrieve and reply negotiation messages of an order; add notes to an order; and cancel an order.

GET Orders {orderId}

	GET /orders/{orderId}
Method	GET
URL or End Point	/colocations/v2/orders/{orderId}
Headers	Authorization, Content-Type
Query Parameters	ibxs
Body	Not applicable

This method retrieves the details of a specific order for an authenticated user. To view this order, the authenticated user from your organization must have Equinix Customer Portal permissions, or they must have permissions to view other users requests. 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.

Copy

curl -X
GET "https://api.equinix.com/colocations/v2/orders/1-188243137021?ibxs=DA4"
-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
orderId	Yes	string	1-188243137021	Order identifier (order ID). Order ID was returned in the response header 'Location' after the order was created. For example, '/orders/1-188243137021' would have been returned as the URL of the newly created cross connect order. Order ID is also known as the order number in the Equinix Customer Portal. If you are not sure of your order ID, see How to retrieve order history? in the Getting Started.

The description of the query parameters is as follows:

Query Parameter Name	Mandatory	Type	Example	Description
ibxs	No	array [strings]	DA4	Filter search by the IBX location codes of the associated IBX data centers. Currently, only 1 IBX location code is supported per query. If an IBX is not specified, all IBXs associated with the order will be returned.

Query Parameter Name

Mandatory

Type

Example

Description

ibxs

array [strings]

DA4

Filter search by the IBX location codes of the associated IBX data centers.

Currently, only 1 IBX location code is supported per query.

If an IBX is not specified, all IBXs associated with the order will be returned.

Copy

{
    "orderId": "1-188243137021",
    "accountName": "ACME CORP",
    "accountNumber": "123456",
    "contacts": [
        {
          "firstName": "John",
          "lastName": "Doe",
          "registeredUser": "johndoe1",
          "availability": "ANYTIME",
          "timezone": "America/Los_Angeles",
          "details": [
            {
                "type": "PHONE",
                "value": "+1-4601231122"
            },
            {
                "type": "EMAIL",
                "value": "johndoe@acmecorp.com"
            },
            {
                "type": "MOBILE",
                "value": "+1-9875432100"
            }
          ],
          "type": "ORDERING"
        },
        {
        "firstName": "John",
        "lastName": "Doe",
        "registeredUser": "johndoe1",
        "availability": "ANYTIME",
        "timezone": "America/Los_Angeles",
        "details": [
             {
                "type": "PHONE",
                "value": "+1-4601231122"
             },
             {
                "type": "EMAIL",
                "value": "johndoe@acmecorp.com"
             },
             {
                "type": "MOBILE",
                "value": "+1-9875432100"
             }
          ],
          "type": "TECHNICAL"
        },
        {
          "firstName": "John",
          "lastName": "Doe",
          "registeredUser": "johndoe1",
          "availability": "ANYTIME",
          "timezone": "America/Los_Angeles",
          "details": [
            {
                "type": "EMAIL",
                "value": "johndoe@acmecorp.com"
            }
        ],
        "type": "NOTIFICATION"
        }
    ],
    "status": "CLOSED",
    "createdDateTime": "2020-10-02T06:03:15.267Z",
    "updatedDateTime": "2020-10-02T07:18:15.267Z",
    "closedDateTime": "2020-10-02T12:05:15.267Z",
    "channel": "PORTAL",
    "subChannel": "ECP",
    "currencyCode": "USD",
    "additionalInfo": [
        {
            "key": "ASSET_ID",
            "value": "4-98765432123"
        },
        {
            "key": "SERIAL_NUMBER",
            "value": "234567890"
        }
    ],
    "customerReferenceId": "EQX_PWR_2020-10/1234",
    "cancellable": false,
    "modifiable": false,
    "details": [
        {
          "lineId": "1-2J3PJADP",
          "parentlineId": "1-2J3PJA23",
          "rootlineId": "1-2J3PJA4E",
          "status": "Completed",
          "description": "AC Circuit - Installation Fee",
          "billingStartDateTime": "2020-10-02T08:04:21.267Z",
          "unitPricing": [
            {
                "value": 0.0,
                "valueType": "ABSOLUTE",
                "type": "ONE_TIME_CHARGE"
            }
        ],
        "totalPricing": [
            {
                "value": 0.0,
                "valueType": "ABSOLUTE",
                "type": "ONE_TIME_CHARGE"
            }
        ],
        "productType": "OTHER",
        "productCode": "POW00003.NR",
        "productName": "AC Circuit - Installation Fee",
        "ibx": "DA4",
        "cage": "DA4:12:ABC000",
        "requestType": "ADD",
        "additionalInfo": [
            {
                "key": "ASSET_ID",
                "value": "4-89137987923"
            },
            {
                "key": "SERIAL_NUMBER",
                "value": "232891719"
            },
            {
                "key": "EXTERNAL_ID",
                "value": "S/No.1001.1.1"
            }
        ],
            "purchaseOrder": {}
        },
        {
        "lineId": "1-2J3PJA23",
        "parentlineId": "1-2J3PJA4E",
        "status": "Completed",
        "description": "AC Circuit ( 120v  / 20-amp  / Single Phase  / Primary )",
        "billingStartDateTime": "2020-10-02T10:02:21.267Z",
        "unitPricing": [
            {
                "value": 0.0,
                "valueType": "ABSOLUTE",
                "type": "ONE_TIME_CHARGE"
            }
        ],
        "totalPricing": [
            {
                "value": 0.0,
                "valueType": "ABSOLUTE",
                "type": "ONE_TIME_CHARGE"
            }
        ],
        "productType": "OTHER",
        "productCode": "POW00003.ELEM",
        "productName": "AC Circuit ( 120v  / 20-amp  / Single Phase  / Primary )",
        "ibx": "DA4",
        "cage": "DA4:12:ABC000",
        "requestType": "ADD",
        "additionalInfo": [
            {
                "key": "ASSET_ID",
                "value": "4-98765432123"
            },
            {
                "key": "SERIAL_NUMBER",
                "value": "234567890"
            },
            {
                "key": "EXTERNAL_ID",
                "value": "S/No.1001.1"
            }
         ],
         "purchaseOrder": {
            "type": "EXISTING",
            "number": "EQXPO12345",
            "closingDate": "2021-12-25"
         }
        },
        {
        "lineId": "1-2J3PJA4E",
        "status": "Completed",
        "description": "Private Cage With kVA Based Power",
        "billingStartDateTime": "2020-10-02T12:02:21.267Z",
        "unitPricing": [
            {
                "value": 0.0,
                "valueType": "ABSOLUTE",
                "type": "ONE_TIME_CHARGE"
            }
        ],
        "totalPricing": [
            {
                "value": 0.0,
                "valueType": "ABSOLUTE",
                "type": "ONE_TIME_CHARGE"
            }
        ],
        "productType": "OTHER",
        "productCode": "SPC00002.PROD",
        "productName": "Private Cage With kVA Based Power",
        "ibx": "DA4",
        "cage": "DA4:12:ABC000",
        "requestType": "UPDATE",
        "additionalInfo": [
            {
                "key": "ASSET_ID",
                "value": "4-98765432123"
            },
            {
                "key": "SERIAL_NUMBER",
                "value": "234567890"
            },
            {
                "key": "EXTERNAL_ID",
                "value": "S/No.1001"
            }
        ],
        "purchaseOrder": {
            "type": "EXISTING",
            "number": "EQXPO12345",
            "closingDate": "2021-12-25"
        },
        "attachments": [
            {
                "id": "f3b1f343-c686-4aba-9968-a1e80dce1fa7",
                "name": "1-206344192607.PDF"
            }
          ]
        }
    ],
    "notes": [
        {
            "id": "1-2ABCD3EF",
            "referenceId": "3-123456781234",
            "createdDateTime": "2020-10-02T07:18:15.267Z",
            "text": "We have completed the order. Please see attached work done.",
            "author": "EQIX_SUPPORT",
            "type": "TECHINCIAN_QUERY",
            "attachments": [
                {
                    "id": "ab2k1234-5678-910e-8d68-a123453a60ab",
                    "name": "3-123456781234.jpg"
                }
            ]
        }
    ],
    "quoteRequestType": "AMENDMENT"  
}

The description of the response payload is as follows:

Field name	Type	Example	Description
orderId	string	1-188243137021	Order ID, also known as the order number in the Equinix Customer Portal. Limit: 1 to 100 characters.
accountName	string	ACME CORP	Customer account name associated with the order.
accountNumber	string	123456	Customer account number associated with the order.
contacts	array [objects]		Contacts array comprises objects representing the ordering, notification and technical contacts. Each object contains the following parameters where applicable: firstName, lastName, registeredUser, availability, timezone, details, type. Equinix communicates with these contacts based on the listed contact information.
firstName	string	John	First name of contact person.
lastName	string	Doe	Last name of contact person.
registeredUser	string	johndoe1	Equinix Customer Portal username of the registered contact. This is only applicable for contacts who are registered users of the Equinix Customer Portal.
availability	string	ANYTIME	Availability of the contact to receive calls from Equinix. Availability - Description ANYTIME - Technical contact is available 24/7. WORK_HOURS - Technical contact is only available during their business hours in their defined timezone.
timezone	string	America/Los_Angeles	Contact's timezone.
details	array [objects]		List of contact details for this person. Each contact detail object consists of the following fields: type, value.
type	string	PHONE	Type of contact detail in the type-value pair. Type - Description PHONE - Primary phone number. EMAIL - Email address. MOBILE - Mobile phone number. This is the secondary contact number.
value	string	+1-4601231122	Value related to the contact detail type in the type-value pair.
type	string	ORDERING	Type of communication contact. Type - Description ORDERING - Ordering contact is the user who submitted this order. NOTIFICATION - Notification contact is the person who will be notified of status updates for this order. TECHNICAL - Technical contact is the person who Equinix can reach for technical clarifications RESELLER - Reseller is the contact person in an organization who made the order on behalf of their customer.
status	string	CLOSED	Current order status. Status - Description RECEIVED - Ticket is entered, booked, or submitted in the system. IN_PROGRESS - Order fulfillment is in progress, or order is in-between status change. ON_HOLD - Order is on hold. Further action may be required from Equinix or customer before order can be fulfilled. CLOSED - Order is fulfilled and closed. CANCELLED - Order is cancelled.
createdDateTime	string	2020-10-02T06:03:15.267Z	Date and time (UTC timezone) the order was created. ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ.
updatedDateTime	string	2020-10-02T07:18:15.267Z	Latest date and time (UTC timezone) the order was updated. ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ.
closedDateTime	string	2020-10-02T12:03:15.267Z	Date and time (UTC timezone) order completed and closed. ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ.
channel	string	PORTAL	Equinix ordering channel. Channel- Description API - Order was submitted via API. PORTAL - Order was submitted through an Equinix Portal Web based application. MOBILE - Order was submitted through an Equinix Portal Mobile App. OFFLINE - Order was submitted to Global Service Desk or to your Customer Success Manager.
subChannel	string	ECP	Specific Equinix ordering sub-channel. This is the specific service through which the order originated, if applicable. For example, an order with channel 'PORTAL' and sub-chanel 'ECP' means the other came through the Equinix Customer Portal Web based application. Sub-channel - Description ECP - Equinix Customer Portal ECX - Equinix Fabric IX - Equinix Internet Exchange NE - Network Edge EMG - Equinix Messaging Gateway QUOTE - Quotation
currencyCode	string	USD	Billing currency. Format: ISO 4217 Currency Code For a full list of currency codes, see Currency Codes in the Appendix.
additionalInfo	array [objects]		List of any additional details or information related to this order line. Each information object comprises the following fields: key, value.
key	string	ASSET_ID	Name of the key in the key-value pair. For more information on the additional details that can be associted with an order, see
value	string	4-98765432123	Value related to the key in the information key-value pair.
customerReferenceId	string	EQX_PWR_2020-10/1234	Customer's reference ID for this order. This was provided by customer during order submission. Limit: 5 to 100 characters.
cancellable	boolean	false	Indicates if the order can still be cancelled. If true, the order can be cancelled. If false, otherwise.
modifiable	boolean	false	Indicates if the order can still be modified. If true, the order can be modified. If false, otherwise.
details	array [objects]		List of order line details specific to this order. Each order line object contains the following parameters where applicable: lineId, parentLineId, rootLineId, status, description, billingStartDateTime, unitPricing, totalPricing, productType, productCode, productName, ibx, cage, cabinets, requestType, additionalInfo, attachments.
lineId	string	1-2J3PJADP	ID of the order line. Each order line ID is unique.
parentLineId	string	1-2J3PJA23	ID of the parent order line for lineId, if this order line is part of a hierarchy that is more than two levels. This is null when the order line is at the root line level.
rootLineId	string	1-2J3PJA4E	ID of the root order line. This is the first level (root) order line. For example, rootLineId1-2J3PJA4E is the first-level order line, parentLineId 1-2J3PJA23 stems from this first-level order line, and lineId 1-2J3PJADP directly stems from parentLineId .
status	string	Completed	Current status of the order line.
description	string	AC Circuit - Installation Fee	Description of the order line. Limit: 5 to 4000 characters.
billingStartDateTime	string	2020-10-02T08:04:21.267Z	Date and time that Equinix billing has started for this order line. Billing is triggered when the order line is completed or closed.
unitPricing	array [objects]		Price per unit of this order line. Each unit price object comprises the following fields: value, valueType, type.
value	number	0.0	Numerical value of the unit cost of this order line. The pricing terms of this value is defined by the valueType.
valueType	string	ABSOLUTE	Defines the terms of pricing associated with the value. Value type - Description ABSOLUTE - Value is an absolute value in the monetary unit defined by the parameter 'currencyCode'. PERCENTAGE - Value is a percentage.
type	string	ONE_TIME_CHARGE	Type of charge. Type - Description ONE_TIME_CHARGE - An ad-hoc charge. MONTHLY_CHARGE - A monthly, recurring charge. MONTHLY_DISCOUNT - A discount that is applied on a recurring, monthly basis. ONE_TIME_DISCOUNT - A discount that is applied once.
totalPricing	array [objects]		Total price of this order line. Each total price object comprises the following fields: value, valueType, type.
value	number	0.0	Numerical value of the total cost of this order line. The pricing terms of this value is defined by the valueType.
valueType	string	ABSOLUTE	Defines the terms of pricing associated with the value. Value type - Description ABSOLUTE - Value is an absolute value in the monetary unit defined by the parameter 'currencyCode'. PERCENTAGE - Value is a percentage.
type	string	ONE_TIME_CHARGE	Type of charge. Type - Description ONE_TIME_CHARGE MONTHLY_CHARGE MONTHLY_DISCOUNT ONE_TIME_DISCOUNT
productType	string	OTHER	Type of product ordered. Product type - Description CROSS_CONNECT - Orders for installing cross connections. SMART_HANDS - Orders for Smart Hands requests. WORK_VISIT - Orders for scheduled work visits including registered and non-registered visitors. SECURITY_ACCESS - Orders for granting or removing security access. CONFERENCE_ROOM - Orders for conference room reservations. TROUBLE_TICKET - Orders for trouble tickets. SHIPMENTS - Orders for inbound or outbound shipments. NETWORK_PORTS - Orders for network ports. DEINSTALL_CROSS_CONNECT - Orders for removing cross connections. OTHER - All other order types.
productCode	string	POW00003.NR	Product code paired with 'productName' associated with this order line.
productName	string	AC Circuit - Installation Fee	Product name paired with the 'productCode' associated with this order line. If you are placing work visit orders, the product name displays as: • “Contact” for registered user • “Visitor” for non-registered visitor Refer to the work visit of the 'productType'.
ibx	string	DA4	IBX code associated with this order line.
cage	string	DA4:12:ABC000	Cage ID associated with this order line.
cabinets	string		List of cabinet IDs associated with this order line, if applicable.
requestType	string	ADD	Type of request action associated with this order line. Request type - Description ADD - A new product or part is added. For example, a device or part was upgraded. DELETE - A product or part was removed or deleted. NO_CHANGE - There is no change to the product or part. UPDATE - A product or part was updated.
additionalInfo	array [objects]		Additional information associated with this order line. Each additional detail object comprises the following fields: key, value. For more information about additional info for product type orders, see Orders: Managing Additional Info in the Appendix.
key	string	ASSET_ID EXTERNAL_ID	Name of the detail in the key-value pair.
value	string	4-89137987923 S/No.1001.1.1	Value of associated detail in the key-value pair. In case of external ID (for example S/No.1001.1.1) this is customer's reference ID specific to the order line. This appears when an external ID is mapped to this order line.
purchaseOrder	object		Purchase order information associated with this order line. Purchase order object comprises the following fields: type, number, closingDate.
type	string	EXISTING	Type of purchase order associated with this order line. Type - Description EXEMPTED - Account is exempted from including purchase order information. NEW - New purchase order that has not yet been used. EXISTING - Purchase order that is already in use.
number	string	EQXPO12345	Purchase order reference number.
closingDate	string	2021-12-25	Expiration of the purchase order. Format: YYYY-MM-DD
attachments	array [objects]		Attachments array comprising object(s) with attachment details. Each attachment object contain the following parameters: id, name. You can have up to 5 attachments.
id	string	f3b1f343-c686-4aba-9968-a1e80dce1fa7	Attachment ID. Length: 36 characters.
name	string	1-206344192607.PDF	Name of attachment. Limit: 5 to 100 characters.
notes	array [objects]		Notes array comprises objects that represents all notes and queries from Equinix and the customer for this order. Each object contains the following parameters where applicable: id, createdDateTime, text, referenceId, author, type, attachments.
id	string	1-2ABCD3EF	ID of the specific note.
referenceId	string	3-123456781234	Reference ID related to order activity. This ID is required when replying to a TECHNICIAN_QUERY using the POST Orders {orderId} Notes method.
createdDateTime	string	2020-10-02T07:18:15.267Z	Date and time the note was created.
text	string	We have completed the order. Please see attached work done.	Text in the note. Limit: 5 to 4000 characters.
author	string	EQIX_SUPPORT	Author of the note. For example, EQIX_SUPPORT represents the Equinix technician who authored the note. Author should have 5 or more characters.
type	string	TECHNICIAN_NOTES	Type of note. Type - Description CUSTOMER_QUERY - Customer reply to Equinix technician query. CUSTOMER_NOTES - Notes provided by the customer in text or attachment form. TECHNICIAN_QUERY - Query from the Equinix technician to the customer. Customer query should be sent to response to this Technician query. TECHNICIAN_NOTES - Notes from the Technician to inform the customer of any updates or developments to this ticket.
attachments	array [objects]		Attachments array comprising object(s) with attachment details. Each attachment object contain the following parameters: id, name.
id	string	ab2k1234-5678-910e-8d68-a123453a60ab	Attachment ID. Length: 36 characters.
name	string	3-123456781234.jpg	Name of attachment.
quoteRequestType	string	AMENDMENT	Type of available quotes. For a full list of quote types, see Quote Types in the Appendix.

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

GET Orders {orderId} Negotiations

	GET /orders/{orderId}/negotiations
Method	GET
URL or End Point	/colocations/v2/orders/{orderId}/negotiations
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	Not applicable

This method retrieves the negotiations messages from Equinix to the customer. When an order cannot be fulfilled by the customer expected date and time, the order will be put on hold and Equinix operations will open a negotiation messaging channel to reach out to the customer. To retrieve the negotiation communication, the authenticated user must be the ordering or technical contact for this order. Once the authenticated user replies this message, the negotiation messaging channel will close until Equinix operations opens the channel again.

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.

Copy

curl -X
GET "https://api.equinix.com/colocations/v2/orders/1-188243137021/negotiations"
-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
orderId	Yes	string	1-188243137021	Order identifier (order ID). Order ID was returned in the response header 'Location' after the order was created. For example, 'orders/l1/1-188243137021' would have been returned as the URL of the newly created cross connect order. Order ID is also known as the order number in the Equinix Customer Portal. If you are not sure of your order ID, see How to retrieve order history? in the Getting Started.

Copy

[
    {
        "referenceId": "4-12312312132",
        "orderRequestedDateTime": "2020-08-25T10:24:10.282Z",
        "proposedDateTime": "2020-08-25T11:24:10.282Z",
        "expirationDateTime": "2020-08-25T09:24:10.282Z",
        "expedited": false,
        "createdDateTime": "2020-08-25T06:24:10.282Z",
        "message": "Due to multiple request, unable to process with requested time"
    }
]

The description of the response payload is as follows:

Field name	Type	Description
referenceId	string	Reference ID of the negotiation message. You will need this when replying to the specific message.
orderRequestedDateTime	string	Requested date and time for the order to be fulfilled. The date and time (UTC timezone) follows ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSSZ.
proposedDateTime	string	Alternate date and time proposed by Equinix operations for the order to be fulfilled. The date and time (UTC timezone) follows ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSSZ.
expirationDateTime	string	Date and time the message expires. The date and time (UTC timezone) follows ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSSZ. When a reply is not received by this date and time, this message will expire and you will be unable to retrieve the message. Your order will continue to remain on hold.
createdDateTime	string	Date and time this negotiation message was created by Equinix operations. The date and time (UTC timezone) follows ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSSZ.
expedited	boolean	Indicates if the order is an expedited order. If 'true', order is expedited. If 'false', order is not expedited, and is either a standard or scheduled order.
message	string	Negotiations message from Equinix to the customer. Limit: 5 to 4000 characters

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

POST Orders {orderId} Cancel

	POST /orders/{orderId}/cancel
Method	POST
URL or End Point	/colocations/v2/orders/{orderId}/cancel
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	{reason, attachments [{id, name}], lineIds [...]}

This method cancels a specific order. To cancel an order, the authenticated user must have permissions to view all users' requests, or they must be the ordering or technical contact for this order. 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 sample curl requests for different scenarios.

Cancelling an order without attachment

Copy

curl -X
POST "https://api.equinix.com/colocations/v2/orders/1-188243137021/cancel"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "reason": "This was duplicated.",
}'

Cancelling specific detail lines in an order with attachment

Before creating a request with attachment, call the POST Attachments File under the API Reference section.

Copy

curl -X
POST "https://api.equinix.com/colocations/v2/orders/1-188243137021/cancel"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "reason": "This was duplicated.",
    "attachments": [
        {
          "id": "abc2k1234-5678-910e-8d68-a123453a60ab",
          "name": "CancellationAttachment.docx"
        }
    ],
    "lineIds": [
    "1-AB1234C"
    ]
}'

The description of the URL parameters is as follows:

URL Parameter Name	Mandatory	Type	Example	Description
orderId	Yes	string	1-188243137021	Order identifier (order ID). Order ID was returned in the response header 'Location' after the order was created. For example, 'orders/1-188243137021' would have been returned as the URL of the newly created order. This order ID is also the order number in the Equinix Customer Portal. If you are not sure of your order ID, see How to retrieve order history? in the Getting Started.

The description of the body parameters is as follows:

Body Parameter Name	Mandatory	Type	Example	Applicable Values	Description
reason	Yes	string	This was duplicated.		Reason for cancellation. Limit: 5 to 4000 characters.
attachments	No	array [objects]			An array containing object(s) of the attachment details for documents you want to attach. Each attachment object must contain the following parameters: id, and name. Currently, we support attachments for the following order types: Cross Connects Work Visit When you send attachments in your cancellation request for other order types, the attachments will not be honoured. Up to 5 attachments, each not exceeding 5MB, can be provided in the following formats: bmp, jpg, jpeg, gif, png, tif, tiff, txt, doc, docx, xls, xlsx, ppt, pps, ppsx, pdf, and vsd. Refer to POST Attachments File under the API Reference section for more information.
id	Conditional	string	abc2k1234-5678-910e-8d68-a123453a60ab		Attachment ID. This is mandatory when an attachment is included. You will obtain this value after attaching your file using the POST Attachments File API.
name	Conditional	string	CancellationAttachment.docx		Name of the attachment. This is mandatory when an attachment is included. This is free text input. You will obtain this value after attaching your file using the POST Attachments File API, but you can change the name for your own reference when including this attachment in any order request. Limit: 5 to 100 characters.
lineIds	No	array [strings]	1-AB1234C		Line ID is specific order or order line related to this order that you would like to cancel. Limit: 1 string If you do not know your specific order line ID, refer to GET Orders {orderId} under the API Reference section for more information.

Order cancellation is successfully accepted for processing when an HTTP code of 202 or 204 is returned, and the following response header is returned. There is no response body.

HTTP Response Header Name

Description

Location

URL of the order.

Example: /orders/{orderId}

'orderId' is the order identifier (ID). This is important to retrieve, update, cancel, or add notes to the order. The order ID is also known as the order number in the Equinix Customer Portal.

If you need to see the update reflected urgently or in the event of latency, contact your local Equinix Service Desk.

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

POST Orders {orderId} Negotiations

	POST /orders/{orderId}/negotiations
Method	POST
URL or End Point	/colocations/v2/orders/{orderId}/negotiations
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	Not applicable

This method replies the negotiations message from Equinix to the customer. To reply the negotiation message, the authenticated user must be the ordering or technical contact for this order. Once the authenticated user replies this message, the negotiation messaging channel will close until Equinix operations opens the channel again.

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 to proceed with a cancellation.

Copy

curl -X
POST "https://api.equinix.com/colocations/v2/orders/1-188243137021/negotiations"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "referenceId": "4-9091830",
    "action": "CANCEL",
    "reason": "Cancelling the new time"
}'

The description of the URL parameters is as follows:

URL Parameter Name	Mandatory	Type	Example	Description
orderId	Yes	string	1-188243137021	Order identifier (order ID). Order ID was returned in the response header 'Location' after the order was created. For example, 'orders/l1/1-188243137021' would have been returned as the URL of the newly created cross connect order. Order ID is also known as the order number in the Equinix Customer Portal. If you are not sure of your order ID, see How to retrieve order history? in the Getting Started.

The description of the body parameters is as follows:

Body Parameter Name	Mandatory	Type	Applicable Values	Description
referenceId	Yes	string		Reference ID of the negotiation message.
action	Yes	string	APPROVE, APPROVE_NON_EXPEDITE, CANCEL	Customer action. Action - Description APPROVE - Approve order to proceed according to the proposed date and time from Equinix. APPROVE_NON_EXPEDITE - Approve order to proceed without expedite. The order will proceed according to standard scheduling, and not in the next 2 to 24 hours. CANCEL - Cancel order item.
reason	Conditional	string		Reason for cancellation. This is mandatory when customer decides to cancel the order item. Limit: 5 to 4000 characters

Negotiation message was successfully replied when an HTTP code of 202 or 204 is returned, and the following response header is returned. There is no response body.

HTTP Response Header Name

Description

Location

URL of the order.

Example: /orders/{orderId}

'orderId' is the order identifier (ID). This is important to retrieve, update, cancel, or add notes to the order. The order ID is also known as the order number in the Equinix Customer Portal.

If you need to see the update reflected urgently or in the event of latency, contact your local Equinix Service Desk.

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

POST Orders {orderId} Notes

	POST /orders/{orderId}/notes
Method	POST
URL or End Point	/colocations/v2/orders/{orderId}/notes
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	referenceId, text, attachments [{id, name}]

This method can be used to add notes to a specific order. An authenticated user can add notes either by providing additional information or by replying an Equinix technician's queries in the form of text or attachments.

There are two kinds of notes that you can send for your order:

Customer Note: A note initiated by the customer to provide additional information for the order. The authenticated user must have permissions to view all users' requests, or they must be the ordering or technical contact for this order.
Customer Query: A note sent by the customer in response to an Equinix technician's queries. To reply to a technician's queries, the authenticated user must be the ordering or technical contact for this order.

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 sample curl requests for different scenarios.

Customer Note with text and attachment
A customer note is a note type sent in the form of text, or text and attachments to add more information to your order.

Before creating a request with attachment, call the POST Attachments File under the API Reference section.

Copy

curl -X
POST "https://api.equinix.com/colocations/v2/orders/1-188243137021/notes"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "text": "Take the light level reading.",
    "attachments": [
    {
        "id": "abc2k1234-5678-910e-8d68-a123453a60ab",
        "name": "UpdateAttachment.docx"
    }
    ]
}'

Customer Query with text and attachment
A customer query is a note type sent in the form of text, or text and attachments to reply an Equinix technician's query.

Before creating a request with attachment, call the POST Attachments File under the API Reference section.

Copy

curl -X
POST "https://api.equinix.com/colocations/v2/orders/1-188243137021/notes"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "referenceId": "3-123456789005",
    "text": "Take the light level reading. Attachment as requested.",
    "attachments": [
    {
        "id": "abc2k1234-5678-910e-8d68-a123453a60ab",
        "name": "UpdateAttachment.docx"
    }
    ]
}'

The description of the URL parameters is as follows:

URL Parameter Name	Mandatory	Type	Example	Description
orderId	Yes	string	1-188243137021	Order identifier (order ID). Order ID was returned in the response header 'Location' after the order was created. For example, 'orders/1-188243137021' would have been returned as the URL of the newly created order. This order ID is also the order number in the Equinix Customer Portal. If you are not sure of your order ID, see How to retrieve order history? under the Getting Started.

The description of the body parameters is as follows:

Body Parameter Name	Mandatory	Type	Example	Applicable Values	Description
referenceId	No	string	3-123456789005		Reference ID of the technician's query. This is mandatory when replying to a technician's query. Only the ordering or technical contact may reply to a technician's query. If you do not include the reference ID when replying a technician's query, the order status will not be updated, and will remain "ON_HOLD". Limit: 1 to 50 characters.
text	Yes	string	Take the light level reading.		Text of the note or query. This is free text input. If your text exceeds this field, you may include it as an attachment. Limit: 5 to 4000 characters.
attachments	No	array [object]			Attachments array comprising object(s) with attachment details. Each attachment object contains the following parameters: id, and name. Currently, support for attachments varies according to the order and note types. Refer to the following list of orders for the corresponding note types that support attachments: Cross connects orders - Customer Note and Customer Query Shipments orders - Customer Query Work visit orders - Customer Note and Customer Query When you send attachments in notes for other order types, the attachments will not be honoured. Up to 5 attachments, each not exceeding 5MB, can be provided in the following formats: bmp, jpg, jpeg, gif, png, tif, tiff, txt, doc, docx, xls, xlsx, ppt, pps, ppsx, pdf, and vsd. See POST Attachments File in the API Reference section for more information.
id	Conditional	string	abc2k1234-5678-910e-8d68-a123453a60ab		Attachment ID. This is mandatory when an attachment is included. You will obtain this value after attaching your file using the POST Attachments File API.
name	Conditional	string	UpdateAttachment.docx		Name of the attachment. This is mandatory when an attachment is included. This is free text input. You will obtain this value after attaching your file using the POST Attachments File API, but you can change the name for your own reference when including this attachment in any order request. Limit: 5 to 100 characters.

Notes are successfully accepted when an HTTP code of 202 or 204 is returned, and the following response header is returned. There is no response body.

HTTP Response Header Name

Description

Location

URL of the order.

Example: /orders/{orderId}

'orderId' is the order identifier (ID). This is important to retrieve, update, cancel, or add notes to the order. The order ID is also known as the order number in the Equinix Customer Portal.

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

GET Orders {orderId}

GET Orders {orderId} Negotiations

POST Orders {orderId} Cancel

POST Orders {orderId} Negotiations

POST Orders {orderId} Notes

Was this documentation helpful?