Skip to main content
Index

Shipments (V2)

Shipments (V2) API allows a user with Shipments ordering permission to schedule inbound or outbound shipments, and to update scheduled shipments. 

 

To schedule inbound or outbound shipments using Shipments (V2) API, see Schedule shipments under the How to Guide section. All other methods can be found below.

PATCH Shipments {orderId}

PATCH /orders/shipments/{orderId}

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

 details { carrier, carrierName, numberOfBoxes, declaredValue, declaredValueCurrency, carrierTrackingNumbers [ ... ], cageDelivery, requirePickup, insureShipment }, requestedDateTime, contacts [ { type, registeredUsers [ ... ] }

 

This method partially updates an inbound or outbound shipment order that is not cancelled or completed. To update this shipment order, the authenticated user must have permission to view all users' requests, or they must be the ordering or technical contact for this shipment. 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, the user can update the following in an inbound or outbound shipment order:

  • shipment details (specific to inbound or outbound shipment type)
  • shipment date
  • notification contacts

 

If you would like to add additional information instead, see POST Orders {orderId} Notes under the API Reference section.

 

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 these different scenarios:

(A) Update all applicable shipment details in an inbound shipment, as well as the shipment date and notification contacts

(B) Update all applicable shipment details in an outbound shipment, as well as the shipment date and notification contacts

 

(A) Update all applicable shipment details in an inbound shipment, as well as the shipment date and notification contacts

In this sample request, the inbound shipment is updated with all the applicable parameters for an inbound shipment update.

 

curl -X

PATCH "https://api.equinix.com/colocations/v2/orders/shipments/1-188243137021"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

   "details": {

    "carrier": "OTHER",
    "carrierName": "New Carrier",
    "numberOfBoxes": 2,
    "carrierTrackingNumbers": [
        "t1Z294AK92654678989",
        "t1Z086DK96424456780"
    ],

    "cageDelivery": true,
  },

   "requestedDateTime": "2020-11-02T10:45:41Z",

   "contacts": [
    {

     "type": "NOTIFICATION",
      "registeredUsers": [
        "janesmith123",
        "johndoe1"
      ]
    }
  ]
}'

 

(B) Update all applicable shipment details in an outbound shipment, as well as the shipment date and notification contacts

In this sample request, the outbound shipment is updated with all the applicable parameters for an outbound shipment update.

 

curl -X

PATCH "https://api.equinix.com/colocations/v2/orders/shipments/1-188243137021"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

   "details": {
    "carrier": "OTHER",
    "carrierName": "New Carrier",
    "numberOfBoxes": 2,

    "carrierTrackingNumbers": [
      "t1Z294AK92654678989",
      "t1Z086DK96424456780"
    ],
    "declaredValue": 1000,
    "declaredValueCurrency": "EUR",
    "requirePickup": true,
    "insureShipment": true
  },

   "requestedDateTime": "2020-11-02T10:45:41Z",

   "contacts": [
    {

     "type": "NOTIFICATION",
      "registeredUsers": [
        "janesmith123",
        "johndoe1"
      ]
    }
  ]
}'

 

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 work visit order was created. For example, 'orders/1-188243137021' would have been returned as the URL of the newly created shipment order. This order ID is also the work visit order number in the Equinix Customer Portal.

 

If you are not sure of your order ID, see How to retrieve order history? in the How to Guide section. 

 

The description of the body parameters is as follows:

 

When 'Conditional' is indicated for a Body Parameter, refer to Description for further details. 

 

Body Parameter Name Mandatory Type Example Applicable Values Description
details No object    

Shipment details.

 

An inbound shipment object comprises the following parameters where applicable: carrier, carrierName, numberOfBoxes, carrierTrackingNumbers, cageDelivery. 

 

An outbound shipment object comprises the following parameters where applicable: carrier, carrierName, numberOfBoxes, carrierTrackingNumbers, declaredValue, declaredValueCurrency, shipmentLabelRequired, shipmentAddress, shipmentAttachmentId, requirePickup, insureShipment.

When updating any shipment details, ensure all details that were passed in the original shipment order that you wish to remain unchanged are also are passed in this request.

For example, when you would only like to change the carrier for your inbound shipment, you would need to pass the following parameters in your request: carrier, numberOfBoxes, carrierTrackingNumbers, cageDelivery (if cageDelivery was originally true).

 

Similarly, when you would like to change the carrier for your outbound shipment, you would need to pass the following parameters in your request: carrier, numberOfBoxes, carrierTrackingNumbers, declaredValue, declaredValueCurrency, shipmentLabelRequired, shipmentAddress or shipmentAttachmentId (if shipmentLabelRequired was is true), requirePickup (if requirePickup was originally true), insureShipment (if insureShipmentwas originally true).

carrier No string OTHER

DHL,

FEDEX,

OTHER,

UPS

The name of the carrier service. 

 

When your carrier is not listed, select OTHER and provide the name of your carrier in the parameter 'carrierName'.

carrierName Conditional string New Carrier  

The name of the unlisted carrier service. This is mandatory when your carrier is OTHERS.

 

This is free text input. 

 

Limit: 1 to 50 characters.

numberOfBoxes No number 2  

Total number of boxes in this shipment. 

 

Limit: 1 to 100. 

carrierTrackingNumbers No

array

[strings]

t1Z294AK92654678989,

t1Z086DK96424456780

 

Tracking number(s). At least one tracking number must be included when a carrier service is delivering the shipment. Multiple tracking numbers should be comma-separated.

 

This is free text input.

 

Limit per tracking number: 1 to 100 characters.

 

Limit: 1 to 10 tracking numbers.

cageDelivery No boolean true

true,

false

A Smart Hands request for Equinix to deliver the shipment to your cage or suite. This is only applicable to inbound shipment.

 

If 'true', shipment will be delivered to customer cage by Equinix. Smart Hands fees will apply.

 

Additional Smart Hands fees may be applied to your account at your contracted rate after the package delivery has been completed. There is no need to create a separate Smart Hands order.

 

If 'false', the customer will pick up the shipment from the IBX shipping dock. Shipments must be picked up within 5 days of delivery. After 5 days, if all attempts to contact the customer results in no response, further action will be taken. Refer to Global IBX Policies for additional details.

declaredValue Conditional number 1000

 

Total declared shipment value. This is only applicable to outbound shipment.

declaredValueCurrency No string EUR Click here for applicable values.

Associated currency of the declared shipment value. This is only applicable to outbound shipment.


Default value: USD.

requirePickup No boolean true

true,

false

Smart Hands request to pick up boxes from cage or suite. This is only applicable to outbound shipment.

 

If 'true', Equinix will pick up boxes from cage or suite to be shipped out. Smart Hands fees will apply.

 

Additional Smart Hands fees may be applied to your account at your contracted rate after the package pick up has been completed. There is no need to create a separate Smart Hands order.

 

If 'false', you will move your shipments from your cage to the shipping area.

insureShipment No boolean true

true,

false

Smart Hands request to insure the shipment. This is only applicable to outbound shipment.

 

If 'true', Equinix will provide insurance for the shipment. Smart Hands fees will apply.

 

Additional Smart Hands fees may be applied to your account at your contracted rate after the insurance service is completed. There is no need to create a separate Smart Hands order.

 

If 'false', insurance is not required.

requestedDateTime No string 2020-11-02T10:45:44Z  

Requested shipment date and time. Dock hours are from 07:00 to 17:00. The selected date and time should be more than 24 hours from now.

 

Additional fees may be applied for deliveries during non-business hours (after hours or weekend deliveries) require prior approval and will be billed to your account as an Equinix Smart Hands fee.

 

Provide a date and time (UTC timezone) in the following ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ 

contacts No

array

[objects]

   

Contacts array consists of the notification contact object. The contacts object contains the following parameters: registeredUsers, and type. 

 

Limit: 1 object

 

This notification contacts object will serve as the latest list of registered users to receive notifications for this order. All registered users included in this object will completely replace the existing list of users. If you would like to add more users to the existing list, ensure that the existing list of registered usernames are not left out in this object.

type Conditional string

NOTIFICATION

NOTIFICATION

Defines the registered contact type. This is mandatory for contacts. 

registeredUsers Conditional

array

[strings]

janesmith123,

johndoe1

 

List of Equinix Customer Portal usernames of the registered contacts. This is mandatory for contacts. Each string in the array represents one contact's username.

 

Equinix Customer Portal user's status must be approved, active, or locked. If the user's status is not any of these, the request will fail. 

 

Limit for notification contacts: 1 to 10 strings. 

 

Order is successfully updated when an HTTP code of 202 or 204 and the following response header are 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.