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 Getting Started 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, shipmentAddress { carrierAccountNumber, shipToName, addressLine1, addressLine2, city, state, countryCode, zipCode, phoneNumber}, shipmentAttachmentId, 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 Access Token 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",
    "shipmentAddress": {
      "carrierAccountNumber": "90123-4567-890",
      "shipToName": "John Doe Corp. Attn: Jane Smith, IT Dept.",
      "addressLine1": "1122 Main Street",
      "city": "New City",
      "state": "CA",
      "countryCode": "US",
      "zipCode": "12345",
      "phoneNumber": "+1 123-456-7890"
    },
    "shipmentAttachmentId": "f49891fc-d9a5-4b4b-bc65-150b1c5e6dff",
    "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 Getting Started 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, shipmentAddress, shipmentAttachmentId, requirePickup, insureShipment. When updating any shipment details, ensure all details that were passed in the original shipment order that you want 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, shipmentAddress or shipmentAttachmentId (if shipmentLabelRequired was originally true), requirePickup (if requirePickup was originally true), insureShipment (if insureShipment was 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'. For outbound shipment, 'shipmentAddress' or 'shipmentAttachmentId' is required when carrier is changed.
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. For outbound shipment, 'shipmentAddress' or 'shipmentAttachmentId' is required when carrier name is changed.
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.
shipmentAddress	Conditional	object			Shipment destination address and carrier account information that are necessary for the shipping label. This is mandatory when you require an Equinix-printed shipping label, and you are not providing the required details in shipmentAttachmentId. This object comprises the following parameters: carrierAccountNumber, shipToName, addressLine1, addressLine2, city, state, countryCode, zipCode, phoneNumber.
carrierAccountNumber	Conditional	string	90123-4567-890		Your selected carrier account number. This is mandatory when including shipmentAddress. Limit: 1 to 100 characters.
shipToName	Conditional	string	John Doe Corp. Attn: Jane Smith, IT Dept.		Shipment recipient name.This is mandatory when including shipmentAddress. Limit: 1 to 100 characters.
addressLine1	Conditional	string	1122 Main Street		Line 1 of the destination address. This is mandatory when including shipmentAddress. Limit: 1 to 50 characters.
addressLine2	No	string			Line 2 of the destination address. Limit: 1 to 50 characters.
city	Conditional	string	New City		City of the destination address. This is mandatory when including shipmentAddress. Limit: 1 to 100 characters.
state	Conditional	string	CA		State of the destination address. This is mandatory when including shipmentAddress. Limit: 1 to 100 characters.
countryCode	Conditional	string	US	Click here for applicable values.	Country code of the destination address. This is mandatory when including shipmentAddress. Format: ISO-3166 ALPHA-2 code.
zipCode	Conditional	string	12345		Postal code or zip code of the destination address. This is mandatory when including shipmentAddress. Limit: 1 to 100 characters.
phoneNumber	Conditional	string	+1 123-456-7890		Contact number of the shipment recipient. This is mandatory when including shipmentAddress. Phone numbers should be prefixed by '+' country code. For example, +1-987-654-3210 or +1 987 654 3210. Limit: 1 to 20 characters.
shipmentAttachmentId	Conditional	string	f49891fc-d9a5-4b4b-bc65-150b1c5e6dff		Attachment for shipping label details. This is mandatory when you require an Equinix-printed shipping label, and you are not providing the required details in shipmentAddress. You may also include this when you want to attach a copy of your own shipping label. The attachment, each not exceeding 2MB, 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. Limit: 36 characters. Refer to POST Attachments File under the API Reference section for more information.
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.
`DEPRECATION` insureShipment	No	boolean	true	true, false	`DEPRECATION: We no longer insure outbound shipments. This field will be retired on 30 September 2022.` 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.

PATCH Shipments {orderId}​

PATCH Shipments {orderId}