API Reference | ReDoc

Shipping Order

Product Info

The Shipping Order API allows for seamless integration and management of delivery orders across multiple providers. It offers functionality for creating, modifying, tracking, and canceling orders, ensuring a streamlined and efficient workflow for businesses and retailers.

Business Values

  • Order Lifecycle Management: - Effortlessly create and manage shipping orders with real-time editing capabilities. This API supports the complete order lifecycle, offering flexibility and adaptability to accommodate diverse workflows.

  • Multi-Provider Integration: - Efficiently retrieve and evaluate shipping estimates from a global network of providers, dynamically selecting the best-fit provider through customizable orchestration rules to optimize efficiency and elevate customer satisfaction.

  • Tracking and Status Updates: - Track shipping orders throughout their entire lifecycle with real-time visibility. Receive instant updates through configurable webhooks and alerts, ensuring transparency and proactive monitoring.

How does it work once I am setup as a user?

After onboarding as a user, seamlessly integrate this API into your eCommerce or operations platform. Simply submit order details to asynchronously create a shipping order, generate a shipping label via the API, and initiate the delivery process. This integration connects you to a global network of delivery providers, offering flexible, reliable, and efficient shipping solutions customized to align with your brand’s unique requirements.

FAQs

  • What information does a Shipping Order contain?

    A Shipping Order encompasses all the essential details required to facilitate shipment, including the shipping origin and destination addresses, recipient contact information, and shipping schedules or preferences.

  • What happens when an order is submitted?

    When a shipping order request is submitted, the platform retrieves shipping estimates from integrated providers and leverages customizable orchestration rules to select the most suitable provider, optimizing efficiency and enhancing customer satisfaction.

Error Codes

When the system is unable to respond to a request, be it from a malformed request, an illegal or invalid value, or other issues, the API generates an error response.

Successful response may or may not include warnings.

  1. Without warnings - Indicates the request has been processed as anticipated.
  2. With warnings - Indicates the request has been processed with potentially unanticipated results. The warning contains information in the response that should be passed to the end user.

The severity of an error may be transient or hard.

  • Transient error - Indicates an error that is temporary in nature. Such errors may be caused by response timeouts due to high server loads or scheduled maintenance in progress. The request may be issued successfully at a later time.
  • Hard error - Indicates the request has a problem that the system is not able to resolve. These errors are critical and prevent requests from processing.

/shipments

POST

Type HTTP Code Severity Description
UNAUTHORIZED 401 Hard Unauthorized: Invalid or missing authentication token
INTERNAL_SERVER_ERROR 500 Transient Internal Server Error: An unexpected error occurred while processing the request
VALIDATION_ERROR 400 Hard Invalid Data: locationExternalId is a required field or Delivery Address not provided or other invalid values in the request
INVALID_DATA 422 Hard Invalid Data: No such locationExternalId exists in our system. Please provide a valid locationExternalId.
DUPLICATE_ID 422 Hard Resource with provided id already exists.
DUPLICATE_NAME 422 Hard Resource with provided name already exists.
DUPLICATE_RESOURCE 422 Hard Resource already exists.
NO_PROVIDER_ASSIGNED 422 Hard No Provider has been assigned to the mentioned location.
NO_PROVIDER_MATCHED 422 Hard No Provider matched the criteria for the requested delivery.
PLACE_ORDER_FAILED 422 Transient Failed to place the requested order with the configured providers.
GEOCODING_FAILED 422 Hard Geocoding Service for the given address failed.
TOO_MANY_REQUESTS 429 Transient Too many requests received per second.
UNMAPPED_ERROR 422 Transient Request received unidentifiable error response.

/shipments/list

POST

Type HTTP Code Severity Description
UNAUTHORIZED 401 Hard Unauthorized: Invalid or missing authentication token
INTERNAL_SERVER_ERROR 500 Transient Internal Server Error: An unexpected error occurred while processing the request
INVALID_DATA 400 Hard Invalid Data: lastUpdatedAt date range cannot be greater than 30 days

/shipments/{shipment_external_id}

GET

Type HTTP Code Severity Description
UNAUTHORIZED 401 Hard Unauthorized: Invalid or missing authentication token
INTERNAL_SERVER_ERROR 500 Transient Internal Server Error: An unexpected error occurred while processing the request
INVALID_DATA 422 Hard Invalid data: Invalid Order Id
NOT_FOUND 404 Hard Not Found: Order with id, 1908241-0061, is not found

DELETE

Type HTTP Code Severity Description
UNAUTHORIZED 401 Hard Unauthorized: Invalid or missing authentication token
INTERNAL_SERVER_ERROR 500 Transient Internal Server Error: An unexpected error occurred while processing the request
NOT_FOUND 404 Hard Order with id, 19345234, is not found
CANCELLATION_NOT_ALLOWED 403 Hard Provider does not allow cancellation of orders.
ORDER_CANCELLATION_FAILED 422 Hard Provider failed to cancel order
ORDER_ALREADY_CANCELED 409 Hard Requested order is already in Cancelled state.
TOO_MANY_REQUESTS 429 Transient Too many requests received per second.
UNMAPPED_ERROR 422 Transient Request received unidentifiable error response.

PUT

Type HTTP Code Severity Description
UNAUTHORIZED 401 Hard Unauthorized: Invalid or missing authentication token
INTERNAL_SERVER_ERROR 500 Transient Internal Server Error: An unexpected error occurred while processing the request
INVALID_DATA 400 Hard Invalid data: The value for the orderValue field is invalid or any other invalid value
VALIDATION_ERROR 400 Hard packages parameter cannot be changed post order dispatch or any other invalid value
NOT_FOUND 404 Hard Order with id, 19345234, is not found
NO_PROVIDER_ASSIGNED 422 Hard No Provider has been assigned to the mentioned location.
NO_PROVIDER_MATCHED 422 Hard No Provider matched the criteria for the requested delivery.
PLACE_ORDER_FAILED 422 Transient Failed to place the requested order with the configured providers.
GEOCODING_FAILED 422 Hard Geocoding Service for the given address failed.
TOO_MANY_REQUESTS 429 Transient Too many requests received per second.
UNMAPPED_ERROR 422 Transient Request received unidentifiable error response.

/shipments/{shipment_external_id}/status-history

GET

Type HTTP Code Severity Description
UNAUTHORIZED 401 Hard Unauthorized: Invalid or missing authentication token
INTERNAL_SERVER_ERROR 500 Transient Internal Server Error: An unexpected error occurred while processing the request

/shipments/{shipment_external_id}/retry

POST

Type HTTP Code Severity Description
UNAUTHORIZED 401 Hard Unauthorized: Invalid or missing authentication token
INTERNAL_SERVER_ERROR 500 Transient Internal Server Error: An unexpected error occurred while processing the request
NOT_FOUND 404 Hard Order with id, 19345234, is not found
INVALID_DATA 422 Hard Order Id value is invalid
INVALID_OPERATION 409 Hard The Order can no longer be retried
NO_PROVIDER_ASSIGNED 422 Hard No Provider has been assigned to the mentioned location.
NO_PROVIDER_MATCHED 422 Hard No Provider matched the criteria for the requested delivery.
PLACE_ORDER_FAILED 422 Transient Failed to place the requested order with the configured providers.
TOO_MANY_REQUESTS 429 Transient Too many requests received per second.
UNMAPPED_ERROR 422 Transient Request received unidentifiable error response.

Create Shipping

Use this API to place a Shipment synchronously from the selected location to the Shipment address.

Response to be validated for API contract and shared as ORDER_DISPATCHED in the response.

User to rely on the Webhooks for status updates of a Shipment.

SecurityOAuth2ClientCredentials
Request
path Parameters
version
required
string
Default: "v1"

version

Value: "v1"
Request Body schema: application/json
One of:
orderExternalId
required
string <= 100 characters

Identifier for the order generated in the client system

groupId
string <= 100 characters

Group ID used to group multiple orders together, providing a combined post-purchase experience.

TimeWindow (object) or null

Time window during which the package will be ready for pickup.

One of:

Time window during which the package will be ready for pickup.

integer or null
One of:

Start of the window. Unix time in milliseconds. (conditional)

integer <int64>

Start of the window. Unix time in milliseconds. (conditional)

integer or null
One of:

End of the window. Unix time in milliseconds. (conditional)

integer <int64>

End of the window. Unix time in milliseconds. (conditional)

TimeWindow (object) or null

Time window during which the package must be delivered.

One of:

Time window during which the package must be delivered.

integer or null
One of:

Start of the window. Unix time in milliseconds. (conditional)

integer <int64>

Start of the window. Unix time in milliseconds. (conditional)

integer or null
One of:

End of the window. Unix time in milliseconds. (conditional)

integer <int64>

End of the window. Unix time in milliseconds. (conditional)

locationExternalId
required
string <= 100 characters

Unique identifier for the pickup location (see Create Location API).

required
object (Address)

Address of the location

street1
required
string <= 100 characters

Address Line 1 (Street Number and Street Name)

street2
string <= 100 characters

Address Line 2 (not to be used for apartment / suite

apartmentNumber
string <= 50 characters

Apartment / Suite

city
string <= 100 characters

City

state
string <= 100 characters

State

postalCode
required
string <= 20 characters

Postal code or zip.

countryCode
string
Default: "US"

2-letter country code in ISO 3166-1 alpha-2 format. If not provided defaults to 'US'.

Enum: "US" "CA" "GB" "AU" "IE"
latitude
number <double>

Latitude coordinates of the address

longitude
number <double>

Longitude coordinates of the address

required
object (Customer)
name
required
string <= 100 characters

Name of the customer

email
string <= 100 characters

Email address of the customer

phone
required
string <= 20 characters

Phone number of the customer

userExternalId
string <= 100 characters

External identifier for the user

Array of objects (Item) <= 100 items

Array of items included in the shipment order. Each item in this list represents a unique SKU with its associated details and quantities. These items are referenced by the itemList property within the package.

Array (<= 100 items)
sku
required
string <= 100 characters

An ID that identify the product/variant from the brand's catalog.

upc
string <= 100 characters

Universal Product Code for the item

category
string <= 100 characters

Category of Item

quantity
integer <int32> >= 1

Number of items of the SKU

object (Size)

Dimensions of the item.

object (Weight)

Weight of an item

price
number <double> >= 0

Retail price of the item.

salePrice
number <double> >= 0

Sale price of the item.

image
string <= 200 characters

Link to the image file of the item.

title
string <= 200 characters

Title of the item.

description
string <= 10000 characters

Description of the item.

itemAttributes
object

Custom item attributes.

tags
Array of strings [ 0 .. 20 ] items

Additional information related to the item.

object (Shipping-Order-API_components-schemas-Package)

Package Details

name
required
string <= 100 characters
Default: "custom"

Name of package created in our system, or pass the value 'custom'.

description
string <= 10000 characters

A brief description about the package contents.

object (Size)

Dimensions of the item.

height
required
number <double> >= 0

Height

width
required
number <double> >= 0

Width

length
required
number <double> >= 0

Length

unit
required
string

units for given size in cm or in

Enum: "cm" "in"
object (Weight)

Weight of an item

value
required
number <double> >= 0

weight

unit
required
string

units for given weight in kg or lb

Enum: "kg" "lb"
itemQuantity
integer <int32> >= 1

Number of items in a single package.

Array of objects (Item) <= 1000 items

Array of items in the package.

Array (<= 1000 items)
sku
required
string <= 100 characters

An ID that identify the product/variant from the brand's catalog.

upc
string <= 100 characters

Universal Product Code for the item

category
string <= 100 characters

Category of Item

quantity
integer <int32> >= 1

Number of items of the SKU

object (Size)

Dimensions of the item.

object (Weight)

Weight of an item

price
number <double> >= 0

Retail price of the item.

salePrice
number <double> >= 0

Sale price of the item.

image
string <= 200 characters

Link to the image file of the item.

title
string <= 200 characters

Title of the item.

description
string <= 10000 characters

Description of the item.

itemAttributes
object

Custom item attributes.

tags
Array of strings [ 0 .. 20 ] items

Additional information related to the item.

temperatureControl
string

Temperature information of the package

Enum: "frozen" "refrigerated" "cool" "ambient" "warm" "none"
content
Array of strings

Content information of the package

Items Enum: "alcohol" "fragile" "tobacco" "rx" "perishable"
barcode
string <= 500 characters
Default: "null"

Barcode sent to the provider for scanning the package

signature
string <= 100 characters

Indicates whether a signature is required for the shipment. Defaults to provider-level configuration if not specified.

Enum: "unattended" "required_recipient" "required" "not_required"
string or null

Special instructions for the Delivery location.

One of:

Special instructions for the Delivery location.

<= 10000 characters
string <= 10000 characters

Special instructions for the Delivery location.

orderValue
number >= 0

Total value of the order in major units as a decimal, e.g. 10.00 ($10.00 USD)

locale
string <= 5 characters

"Preferred locale by the customer for the order, following the BCP47 format. Examples: 'en-US' (English - United States), 'fr-CA' (French - Canada)."

createdDate
number

The original creation date of the order in Unix time (milliseconds).

object

Custom key-value pairs for configurable order attributes.

additional property
string or number or boolean or Array of strings or Array of numbers or Array of booleans
One of:
<= 500 characters
string <= 500 characters
Array of objects (ProposedProvider)

Overrides orchestration and places the order with specified providers.

Array
name
required
string <= 1000 characters

Name of the proposed provider

Array of objects (ProposedProviderService)

List of services associated with the provider

object (Pickup)
name
required
string <= 100 characters

Name of the location

locationExternalId
string <= 100 characters

Unique external identifier for the location.

brandExternalId
string <= 100 characters

Unique identifier for the brand associated with the order.

required
object (Address)

Address of the location

street1
required
string <= 100 characters

Address Line 1 (Street Number and Street Name)

street2
string <= 100 characters

Address Line 2 (not to be used for apartment / suite

apartmentNumber
string <= 50 characters

Apartment / Suite

city
string <= 100 characters

City

state
string <= 100 characters

State

postalCode
required
string <= 20 characters

Postal code or zip.

countryCode
string
Default: "US"

2-letter country code in ISO 3166-1 alpha-2 format. If not provided defaults to 'US'.

Enum: "US" "CA" "GB" "AU" "IE"
latitude
number <double>

Latitude coordinates of the address

longitude
number <double>

Longitude coordinates of the address

pickupInstructions
string <= 10000 characters

Pickup instructions for the location.

required
object (Contact)

Contact information.

name
required
string

First Name of Contact

phone
required
string

Phone Number of the Contact

email
string

Email address of the Contact

Array of objects
Array
name
string

name of the provider

object
additional property
string or number
Responses
201

Resource is successfully created

400

Bad Request

401

Unauthorized

422

Processing failed as request contains invalid data

500

Internal server error

post/shipping/{version}/shipments
Request samples
application/json
{
  • "locationExternalId": "7709",
  • "orderExternalId": "7709-001",
  • "orderValue": 10,
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "package": {
    },
  • "itemList": [],
  • "pickupTime": null,
  • "deliveryTime": null
}
Response samples
application/json
{
  • "locationExternalId": "7709",
  • "orderExternalId": "7709-001",
  • "orderValue": 10,
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "package": {
    },
  • "itemList": [],
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "orderAttributes": { },
  • "tenantId": "dummyaccount1",
  • "brandExternalId": "dummyaccount1",
  • "groupId": null,
  • "currencyCode": "USD",
  • "pickupContact": {
    },
  • "pickupAddress": {
    },
  • "status": "ORDER_DISPATCHED",
  • "referenceLinks": {},
  • "provider": {
    },
  • "trackingId": "1ZXXXX",
  • "attachments": null,
  • "vehicle": null,
  • "amount": null,
  • "label": null,
  • "actualDeliveryTime": null,
  • "actualPickupTime": null,
  • "fee": null,
  • "returnRequest": null,
  • "proposedProviders": [ ],
  • "createdAt": "",
  • "lastUpdatedAt": "",
  • "undeliverableOrderReturnLocation": {
    },
  • "returnLocationId": "301"
}

List Shipments

Use this API to retrieve the list of shipments. By default, the shipments placed within the last 24 hours will be retrieved.

SecurityOAuth2ClientCredentials
Request
path Parameters
version
required
string
Default: "v1"

version

Value: "v1"
Request Body schema: application/json
limit
integer <int32> <= 1000

Limit the number of orders in the response. If not passed, the default is 1000. The maximum allowed is 1000.

object (TimeWindow)
integer or null
One of:

Start of the window. Unix time in milliseconds. (conditional)

integer <int64>

Start of the window. Unix time in milliseconds. (conditional)

integer or null
One of:

End of the window. Unix time in milliseconds. (conditional)

integer <int64>

End of the window. Unix time in milliseconds. (conditional)

orderExternalIds
Array of strings <= 100 items

Get the orders for the provided array of orderExternalIds.

groupId
string

Get orders belonging to the provided groupId. This value is case-sensitive.

locationExternalIds
Array of strings <= 100 items

Get the orders for the provided array of locationExternalIds.

object

Get all orders whose pickupTime.startsAt is greater than or equal to the provided value. Only accepts startsAt from the Time Window. If pickupTime is present, deliveryTime.endsAt is required.

integer or null
One of:

Start of the window. Unix time in milliseconds. (conditional)

integer <int64>

Start of the window. Unix time in milliseconds. (conditional)

object

Get all orders whose deliveryTime.endsAt is lesser than or equal to the provided value. Only accepts endsAt from the Time Window. If deliveryTime is present pickupTime.startsAt is required.

integer or null
One of:

End of the window. Unix time in milliseconds. (conditional)

integer <int64>

End of the window. Unix time in milliseconds. (conditional)

object (TimeWindow)
integer or null
One of:

Start of the window. Unix time in milliseconds. (conditional)

integer <int64>

Start of the window. Unix time in milliseconds. (conditional)

integer or null
One of:

End of the window. Unix time in milliseconds. (conditional)

integer <int64>

End of the window. Unix time in milliseconds. (conditional)

status
Array of strings

Get all orders having the provided statuses.

paginationToken
string

The API has a limit of retrieving 1000 orders per call. If limit value is specified in the request, the number of orders are retrieved as per the value indicated in the limit (limit cannot be more than 1000). Use the paginationToken to navigate to the next or previous set of orders.

paginationToken returns an object of next and previous tokens: If there are no results for the next page, the next value would be null. If there are no results for the previous page, the previous value would be null. To navigate to the next set of page results, use the next value from the paginationToken response and set it as the paginationToken value. To navigate to the previous set of page results, use the previous value from the paginationToken response and set it as the paginationToken value.

Responses
200

Request was successful

400

Bad Request

401

Unauthorized

500

Internal server error

post/shipping/{version}/shipments/list
Request samples
application/json
{
  • "limit": 100,
  • "lastUpdatedAt": {
    },
  • "orderExternalIds": [
    ],
  • "locationExternalIds": [
    ],
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "createdAt": {
    },
  • "status": [
    ],
  • "paginationToken": "NjI2N2M5YWIwM2FiNjQ5NDdjYWZiYmMxXzYyNjdjOWFiMDNhYjY0OTQ3Y2FmYmJjMV82MjY3Y2FkNzYyN2Y1ZjY1OGM4YjljNTNfbmV4dA=="
}
Response samples
application/json
{
  • "data": [
    ]
}

Get Shipment

Use this API to retrieve the shipment details with the external Id (shipment_id) that was used in Create Shipment.

SecurityOAuth2ClientCredentials
Request
path Parameters
version
required
string
Default: "v1"

version

Value: "v1"
shipment_id
required
string^[a-fA-F0-9]{24}$

The unique order Id generated by the system after creating order

Example: 60b8d6c9e4b0f5d3a1a6e500
query Parameters
force_update
boolean

To retrieve the latest information from the provider about the shipment, this field should be assigned true

Responses
200

Request was successful

400

Bad Request

401

Unauthorized

404

Resource was not found

500

Internal server error

get/shipping/{version}/shipments/{shipment_id}
Request samples 
Response samples 
application/json
{
  • "id": "5e1f1ef5167ab20010a74b94",
  • "brandExternalId": "demoBrand",
  • "locationExternalId": "NYClocation101",
  • "orderExternalId": "876581",
  • "groupId": "group1",
  • "orderValue": 11,
  • "itemList": [ ],
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "package": {
    },
  • "deliveryInstructions": "Some text for delivery instructions",
  • "orderAttributes": {
    },
  • "estimatedDeliveryTime": {
    },
  • "estimatedPickupTime": {
    },
  • "label": null,
  • "trackingId": "del_MoMtkAakB1LDVk",
  • "referenceLinks": {},
  • "provider": {
    },
  • "amount": 6,
  • "currencyCode": "USD",
  • "pickupContact": {
    },
  • "pickupAddress": {
    },
  • "pickupInstructions": "Always be smiling",
  • "status": "ORDER_CANCELLED",
  • "tenantId": "NYC",
  • "lastUpdatedAt": "2020-01-15T14:17:26.099Z",
  • "createdAt": "2020-01-15T14:17:25.984Z"
}
Cancel Shipment
Use this API to cancel a shipment at both DS and at the Providers system using the shipment_id.


SecurityOAuth2ClientCredentials 
Request 
path Parameters
version
required
string
 Default:  "v1"
version


 Value: "v1"  
shipment_id
required
string^[a-fA-F0-9]{24}$
The unique order Id generated by the system after creating order


 
 Example:  60b8d6c9e4b0f5d3a1a6e500
Responses 
200
Request was successful


401
Unauthorized


404
Resource was not found


409
Conflict between the request and the current state of the resource


422
Bad Request


500
Internal server error


delete/shipping/{version}/shipments/{shipment_id}
Request samples 
Response samples 
application/json
{
  • "id": "62a9e3ce87f3c9df15080f00",
  • "estimatedDeliveryTime": {
    },
  • "estimatedPickupTime": {
    },
  • "referenceLinks": {},
  • "provider": {
    },
  • "amount": null,
  • "locationExternalId": "100983",
  • "orderExternalId": "15June11",
  • "groupId": null,
  • "orderValue": 78.65,
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "proposedProviders": [
    ],
  • "signature": "not_required",
  • "package": {
    },
  • "itemList": [ ],
  • "deliveryInstructions": "The dog may be playing in the yard. Please close the gate once you enter.",
  • "pickupInstructions": "Enter from the staff entrance to pick up the package",
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "orderAttributes": { },
  • "brandExternalId": "devon",
  • "currencyCode": "USD",
  • "pickupContact": {
    },
  • "pickupAddress": {
    },
  • "createdAt": "2022-06-15T13:51:10.096Z",
  • "status": "ORDER_CANCELLED",
  • "tenantId": "dummyaccount1",
  • "lastUpdatedAt": "2022-06-15T13:52:03.524Z"
}
Edit Shipment
Use this API to modify the details of the Shipment after it has been placed in our system.


SecurityOAuth2ClientCredentials 
Request 
path Parameters
version
required
string
 Default:  "v1"
version


 Value: "v1"  
shipment_id
required
string^[a-fA-F0-9]{24}$
The unique order Id generated by the system after creating order


 
 Example:  60b8d6c9e4b0f5d3a1a6e500
query Parameters
force_update
boolean
To forcefully perform an Shipment edit operation this field should be assigned true.


 
Request Body schema: application/json
orderExternalId
string  <= 100 characters 
Client-side identifier for the shipment record


 
groupId
string  <= 100 characters 
Group ID to group a number of orders together


 
TimeWindow (object) or null
Scheduled date and time for the drop-off


 
One of:
Scheduled date and time for the drop-off


integer or null
 
One of:
Start of the window. Unix time in milliseconds. (conditional)


integer <int64> 
Start of the window. Unix time in milliseconds. (conditional)


 
integer or null
 
One of:
End of the window. Unix time in milliseconds. (conditional)


integer <int64> 
End of the window. Unix time in milliseconds. (conditional)


 
TimeWindow (object) or null
Scheduled date and time for the pickup


 
One of:
Scheduled date and time for the pickup


integer or null
 
One of:
Start of the window. Unix time in milliseconds. (conditional)


integer <int64> 
Start of the window. Unix time in milliseconds. (conditional)


 
integer or null
 
One of:
End of the window. Unix time in milliseconds. (conditional)


integer <int64> 
End of the window. Unix time in milliseconds. (conditional)


 
locationExternalId
string  <= 100 characters 
External ID of the delivery location


 
object (Address) 
Address of the location


 
street1
required
string  <= 100 characters 
Address Line 1 (Street Number and Street Name)


 
street2
string  <= 100 characters 
Address Line 2 (not to be used for apartment / suite


 
apartmentNumber
string  <= 50 characters 
Apartment / Suite


 
city
string  <= 100 characters 
City


 
state
string  <= 100 characters 
State


 
postalCode
required
string  <= 20 characters 
Postal code or zip.


 
countryCode
string
 Default:  "US"
2-letter country code in ISO 3166-1 alpha-2 format. If not provided defaults to 'US'.


 Enum: "US" "CA" "GB" "AU" "IE"  
latitude
number <double> 
Latitude coordinates of the address


 
longitude
number <double> 
Longitude coordinates of the address


 
object (Customer) 
 
name
required
string  <= 100 characters 
Name of the customer


 
email
string  <= 100 characters 
Email address of the customer


 
phone
required
string  <= 20 characters 
Phone number of the customer


 
userExternalId
string  <= 100 characters 
External identifier for the user


 
Array of objects (Item)   <= 100 items 
Array of items included in the shipment order. Each item in this list represents a unique SKU with its associated details and quantities. These items are referenced by the itemList property within the package.


 
 Array (<= 100 items)
sku
required
string  <= 100 characters 
An ID that identify the product/variant from the brand's catalog.


 
upc
string  <= 100 characters 
Universal Product Code for the item


 
category
string  <= 100 characters 
Category of Item


 
quantity
integer <int32>   >= 1 
Number of items of the SKU


 
object (Size) 
Dimensions of the item.


 
object (Weight) 
Weight of an item


 
price
number <double>   >= 0 
Retail price of the item.


 
salePrice
number <double>   >= 0 
Sale price of the item.


 
image
string  <= 200 characters 
Link to the image file of the item.


 
title
string  <= 200 characters 
Title of the item.


 
description
string  <= 10000 characters 
Description of the item.


 
itemAttributes
object
Custom item attributes.


 
tags
Array of strings  [ 0 .. 20 ] items 
Additional information related to the item.


 
object (Shipping-Order-API_components-schemas-Package) 
Package Details


 
name
required
string  <= 100 characters 
 Default:  "custom"
Name of package created in our system, or pass the value 'custom'.


 
description
string  <= 10000 characters 
A brief description about the package contents.


 
object (Size) 
Dimensions of the item.


 
height
required
number <double>   >= 0 
Height


 
width
required
number <double>   >= 0 
Width


 
length
required
number <double>   >= 0 
Length


 
unit
required
string
units for given size in cm or in


 Enum: "cm" "in"  
object (Weight) 
Weight of an item


 
value
required
number <double>   >= 0 
weight


 
unit
required
string
units for given weight in kg or lb


 Enum: "kg" "lb"  
itemQuantity
integer <int32>   >= 1 
Number of items in a single package.


 
Array of objects (Item)   <= 1000 items 
Array of items in the package.


 
 Array (<= 1000 items)
sku
required
string  <= 100 characters 
An ID that identify the product/variant from the brand's catalog.


 
upc
string  <= 100 characters 
Universal Product Code for the item


 
category
string  <= 100 characters 
Category of Item


 
quantity
integer <int32>   >= 1 
Number of items of the SKU


 
object (Size) 
Dimensions of the item.


 
object (Weight) 
Weight of an item


 
price
number <double>   >= 0 
Retail price of the item.


 
salePrice
number <double>   >= 0 
Sale price of the item.


 
image
string  <= 200 characters 
Link to the image file of the item.


 
title
string  <= 200 characters 
Title of the item.


 
description
string  <= 10000 characters 
Description of the item.


 
itemAttributes
object
Custom item attributes.


 
tags
Array of strings  [ 0 .. 20 ] items 
Additional information related to the item.


 
temperatureControl
string
Temperature information of the package


 Enum: "frozen" "refrigerated" "cool" "ambient" "warm" "none"  
content
Array of strings
Content information of the package


Items Enum: "alcohol" "fragile" "tobacco" "rx" "perishable"  
barcode
string  <= 500 characters 
 Default:  "null"
Barcode sent to the provider for scanning the package


 
signature
string  <= 100 characters 
Indicates signature requirement


 Enum: "unattended" "required_recipient" "required" "not_required"  
deliveryInstructions
string  <= 10000 characters 
Additional notes related to the shipment


 
orderValue
number  >= 0 
Total value of the order


 
locale
string  <= 50 characters 
 
createdDate
number
Unix timestamp in milliseconds for creation date


 
object
Configurable key-value pairs of custom order attributes


 
additional property
string or number or boolean or Array of strings or Array of numbers or Array of booleans
 
One of:
  <= 500 characters 
string  <= 500 characters 
 
Array of objects (ProposedProvider) 
List of proposed providers for the order


 
 Array 
name
required
string  <= 1000 characters 
Name of the proposed provider


 
Array of objects (ProposedProviderService) 
List of services associated with the provider


 
Responses 
200
Request was successful


400
Bad Request


401
Unauthorized


404
Resource was not found


422
Invalid data provided


500
Internal server error


put/shipping/{version}/shipments/{shipment_id}
Request samples 
application/json
{
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "package": {
    },
  • "orderExternalId": "19082413",
  • "orderValue": 160.99
}
Response samples 
application/json
{
  • "id": "5e1f1ef5167ab20010a74b94",
  • "brandExternalId": "Demobrand",
  • "itemList": [ ],
  • "locationExternalId": "NYClocation101",
  • "orderExternalId": "876581",
  • "groupId": "group1",
  • "orderValue": 11,
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "package": {
    },
  • "deliveryInstructions": "Some text for delivery instructions",
  • "orderAttributes": {
    },
  • "estimatedDeliveryTime": {
    },
  • "estimatedPickupTime": {
    },
  • "label": null,
  • "referenceLinks": {},
  • "trackingId": "del_MoMtkAakB1LDVk",
  • "provider": {
    },
  • "amount": 6,
  • "currencyCode": "USD",
  • "pickupContact": {
    },
  • "pickupAddress": {
    },
  • "pickupInstructions": "Always be smiling",
  • "status": "ORDER_CANCELLED",
  • "tenantId": "NYC",
  • "lastUpdatedAt": "2020-01-15T14:17:26.099Z",
  • "createdAt": "2020-01-15T14:17:25.984Z"
}
Get Shipment Status
Use this API to retrieve the shipment status history with timestamp using the Shipment External Id.


SecurityOAuth2ClientCredentials 
Request 
path Parameters
version
required
string
 Default:  "v1"
version


 Value: "v1"  
shipment_id
required
string^[a-fA-F0-9]{24}$
The unique order Id generated by the system after creating order


 
 Example:  60b8d6c9e4b0f5d3a1a6e500
query Parameters
is_unique
string
 Default:  "false"
Return only unique Shipment status progressions


 
Responses 
200
Request was successful


401
Unauthorized


500
Internal server error


get/shipping/{version}/shipments/{shipment_id}/status-history
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retry Shipment
Use this API to manually retry the place Shipment process again. This API is useful in a scenario where a Shipment fails with a provider due to some parameter value. This field can then be edited and Shipment dispatch can be retried.


SecurityOAuth2ClientCredentials 
Request 
path Parameters
version
required
string
 Default:  "v1"
version


 Value: "v1"  
shipment_id
required
string^[a-fA-F0-9]{24}$
The unique order Id generated by the system after creating order


 
 Example:  60b8d6c9e4b0f5d3a1a6e500
Responses 
201
Shipment retry successful


400
Bad Request


401
Unauthorized


404
Resource was not found


409
Conflict between the request and the current state of the resource


500
Internal server error


post/shipping/{version}/shipments/{shipment_id}/retry
Request samples 
Response samples 
application/json
{
  • "brandExternalId": "demoBrand",
  • "provider": {
    },
  • "trackingId": "1419285376",
  • "estimatedPickupTime": {
    },
  • "estimatedDeliveryTime": {
    },
  • "itemList": [ ],
  • "amount": 10.33,
  • "fee": 10.33,
  • "currencyCode": "USD",
  • "status": "ORDER_DISPATCHED",
  • "referenceLinks": {},
  • "id": "62a9f879a69cdb7a3ad52ebe",
  • "deliveryInstructions": null,
  • "orderExternalId": "19082418",
  • "locationExternalId": "100983",
  • "tenantId": "dummyaccount1",
  • "orderAttributes": { },
  • "attachments": null,
  • "vehicle": null,
  • "label": null,
  • "pickupInstructions": "Enter from the staff entrance to pick up the package",
  • "deliveryContact": {
    },
  • "package": {
    },
  • "pickupAddress": {
    },
  • "deliveryAddress": {
    },
  • "proposedProviders": [ ],
  • "groupId": null,
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "lastUpdatedAt": "2020-01-15T14:17:25.984Z",
  • "createdAt": "2020-01-15T14:17:25.984Z"
}
➔ Next to Tracker