Schedule Shipments

All shipments must be scheduled in advance by creating an inbound or outbound shipment order. Failure to do so may result in the shipment being rejected. Only an Equinix Customer Portal user with Shipments ordering permission can schedule these shipments. The types of shipments currently supported by Equinix Customer Portal APIs may be found here.

Prerequisites

To get shipment details, the user must have Shipments ordering permissions.
Authenticate - Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication. Refer to API Authentication for instructions on how to call the OAuth API to validate and authenticate your credentials.
To schedule a shipment, you need to determine the exact cage ID and account number for the shipment. These values will be passed for the cageId and accountNumber parameters in the request body.
Get Location Information - Send a GET request to the /v1/orders/smarthands/locations endpoint to retrieve available IBX locations that you have access to. You may skip this step if you already know the location information.

Scheduling an Inbound Shipment

To schedule an Inbound Shipment, send a POST request to the [/colocations/v2/orders/shipments](/api-catalog/shipmentsv2/#tag/Shipments/operation/Schedule inbound or outbound shipment) endpoint. Use the "type": "INBOUND" parameter to specify that it is an Inbound Shipment, and provide the rest of the shipment details in the body of the request. An inbound shipment request minimally requires the shipment type, shipment date, associated cage, carrier, and number of boxes to be included. The other necessary information you need to pass in the inbound shipment request body depends on the following:

If your inbound shipment is from a cage linked to multiple accounts.
If the carrier delivering the shipment is from your organization, a listed carrier or an unlisted carrier. If your carrier is not DHL,FedEx, UPS, your carrier is unlisted.

Example cURL Request:

An inbound shipment from a cage associated with a single account that will be delivered by your organization.

For this scenario, your inbound shipment is delivered to your cage linked to only one account by someone from your organization. The minimum required information for this scenario is passed in this sample request.

curl -X  
POST "https://api.equinix.com/colocations/v2/orders/shipments"  
-H "content-type: application/json"  
-H "authorization: Bearer <token>"  
-d '{  
    "type": "INBOUND",  
    "requestedDateTime": "2020-11-02T10:45:41Z",  
    "cageId": "AM1:01:000111",  
    "details": {  
    "carrier": "CUSTOMER_CARRIER",  
    "numberOfBoxes": 2  
    }  
}'

Example cURL Request:

An inbound shipment from a cage associated with multiple accounts that will be delivered by an unlisted carrier. Additional Smart Hands requests, information, contact details, and attachments are also included.

note

Before creating an order with attachment, call the Attachments File endpoint.

In this scenario, you have provided the minimum required information to facilitate an inbound shipment, and included additional body parameters which support the following:

additional Smart Hands request to deliver the shipment to your cage
additional description
supporting attachments
your own reference identifier
purchase order information
contact information for notification or technical contact persons

All available and applicable body parameters are passed in this sample request.

curl -X  
POST "https://api.equinix.com/colocations/v2/orders/shipments"  
-H "content-type: application/json"  
-H "authorization: Bearer <token>"  
-d '{  
    "type": "INBOUND",  
    "requestedDateTime": "2020-11-02T10:45:41Z",  
    "cageId": "AM1:01:000111",  
    "accountNumber": 901011,  
    "details": {  
        "carrier": "OTHER",  
        "carrierName": "New Carrier",  
        "numberOfBoxes": 2,  
        "carrierTrackingNumbers": [  
            "t1Z294AK92654678989",  
            "t1Z086DK96424456780"  
        ],  
        "cageDelivery": true  
    },  
    "description": "Package is fragile and heavy. Handle with care. Additional description in attachment.",  
    "attachments": [  
        {  
            "id": "85d9660a-f877-405a-b38e-8e61a4f77f44",  
            "name": "OrderInstructions.docx"  
        }  
    ],   
    "customerReferenceId": "2020/16347",  
        "purchaseOrder": {  
        "type": "NEW",  
        "number": "9654284",  
        "amount": "10000",  
        "startDate": "2020-10-01",  
        "endDate": "2021-09-30",  
        "attachmentId": "56d10de6-f2c0-4edd-ba29-b70736aa2093"  
    },  
    "contacts": [  
    {  
        "type": "NOTIFICATION",  
        "registeredUsers": [  
            "john_doe1",  
            "jane_smith1"  
        ]  
    },  
    {  
        "type": "TECHNICAL",  
        "firstName": "John",  
        "lastName": "Doe",  
        "availability": "WORK_HOURS",  
        "timezone": "America/Los_Angeles",  
        "details": [  
            {  
                "type": "EMAIL",  
                "value": "johndoe@acme.com""  
            },  
            {  
                "type": "PHONE",  
                "value": "+1-987654321"  
            },  
            {  
                "type": "MOBILE",  
                "value": "+1-912345678"  
            }  
        ]  
    }  
  ]  
}'

The order is successfully created when an HTTP code of 201 is returned and the response header is returned. There is no response body.

If you would like to update this order, see [/v2/orders/shipments/{orderId}](/api-catalog/shipmentsv2/#tag/Shipments/operation/Update inbound or outbound shipment) in the API Reference section for more information.

If you would like to add notes to this order, retrieve and reply negotiations for this order, or cancel this order, see Orders in the API Reference Section for more information.

Schedule an Outbound Shipment

To schedule an Outbound Shipment, send a POST request to the [/colocations/v2/orders/shipments](/api-catalog/shipmentsv2/#tag/Shipments/operation/Schedule inbound or outbound shipment) endpoint. Use the "type": "OUTBOUND" parameter to specify that it is an Outbound Shipment, and provide the rest of the shipment details in the body of the request. An outbound shipment request minimally requires the shipment type, shipment date, associated cage, and carrier to be included. The other necessary information you need to pass in the outbound shipment request body depends on the following:

If your outbound shipment is from a cage linked to multiple accounts.
If the carrier delivering the shipment is from your organization, a listed carrier or an unlisted carrier. If your carrier is not DHL, FedEx, UPS, your carrier is unlisted.
If you require a shipping label to be printed by Equinix.

Example cURL Request:

An outbound shipment from a cage associated with a single account that will be delivered by someone from your organization.

For this scenario, your outbound shipment is delivered to your cage linked to only one account by someone from your organization. The minimum required information for this scenario is passed in this sample request.

curl -X  
POST "https://api.equinix.com/colocations/v2/orders/shipments"  
-H "content-type: application/json"  
-H "authorization: Bearer <token>"  
-d '{  
    "type": "OUTBOUND",  
    "requestedDateTime": "2020-11-02T10:45:41Z",  
    "cageId": "AM1:01:000111",  
    "details": {  
    "carrier": "CUSTOMER_CARRIER"  
    ]  
    }  
}'

Example cURL Request:

An outbound shipment from a cage associated with multiple counts that will be delivered by an unlisted carrier, and requires Equinix to print the shipping label. The relevant shipping label details are provided as an attachment. Additional Smart Hands requests, information, contact details, and attachments are also included.

note

Before creating an order with attachment, call the Attachments File endpoint.

In this scenario, you have provided the minimum required information to facilitate an outbound shipment request, and included additional body parameters which support the following:

declared shipment value in a currency other than USD
additional Smart Hands requests to pick up your shipment from your cage or to insure it
additional description
supporting attachments
your own reference identifier
purchase order information
contact information for notification or technical contact persons

All available and applicable body parameters are passed in this sample request.

curl -X  
POST "https://api.equinix.com/colocations/v2/orders/shipments"  
-H "content-type: application/json"  
-H "authorization: Bearer <token>"  
-d '{  
    "type": "OUTBOUND",  
    "requestedDateTime": "2020-11-02T10:45:41Z",  
    "cageId": "AM1:01:000111",  
    "accountNumber": 901011,  
    "details": {  
    "carrier": "OTHER",  
    "carrierName": "New Carrier",  
    "numberOfBoxes": 2,  
    "declaredValue": 1000,  
    "declaredValueCurrency": "EUR",  
    "carrierTrackingNumbers": [  
        "t1Z294AK92654678989",  
        "t1Z086DK96424456780"  
    ],  
        "shipmentLabelRequired": true,  
        "shipmentAttachmentId": "f49891fc-d9a5-4b4b-bc65-150b1c5e6dff",  
        "requirePickup": true,  
        "insureShipment": true  
    },  
    "description": "Package is fragile and heavy. Handle with care. Additional description in attachment.",  
    "attachments": [  
    {  
        "id": "85d9660a-f877-405a-b38e-8e61a4f77f44",  
        "name": "OrderInstructions.docx"  
    }  
    ],  
    "customerReferenceId": "2020/16347",  
    "purchaseOrder": {  
        "type": "NEW",  
        "number": "9654284",  
        "amount": "10000",  
        "startDate": "2020-10-01",  
        "endDate": "2021-09-30",  
        "attachmentId": "56d10de6-f2c0-4edd-ba29-b70736aa2093"  
    },  
    "contacts": [  
    {  
        "type": "NOTIFICATION",  
        "registeredUsers": [  
            "john_doe1",  
            "jane_smith1"  
        ]  
    },  
    {  
        "type": "TECHNICAL",  
        "firstName": "John",  
        "lastName": "Doe",  
        "availability": "WORK_HOURS",  
        "timezone": "America/Los_Angeles",  
        "details": [  
            {  
                "type": "EMAIL",  
                "value": "johndoe@acme.com"  
            },  
            {  
                "type": "PHONE",  
                "value": "+1-987654321"  
            },  
            {  
                "type": "MOBILE",  
                "value": "+1-912345678"  
            }  
        ]  
    }  
  ]  
}'

The order is successfully created when an HTTP code of 201 is returned and the response header is returned. There is no response body.

If you would like to add notes to this order, retrieve and reply negotiations for this order, or cancel this order, see Orders in the API Reference Section for more information.

Prerequisites​

Scheduling an Inbound Shipment​

Schedule an Outbound Shipment​

Prerequisites

Scheduling an Inbound Shipment

Schedule an Outbound Shipment