API Reference | ReDoc

Delivery Order

Product Info

The Delivery Order API streamlines the creation and management of delivery orders across an extensive network of providers. Designed for retailers and businesses, it serves as a centralized solution for handling every phase of the delivery process, from initiation to completion.

Business Values

  • Order Lifecycle Management: - Seamlessly create and manage delivery orders, including real-time edits. Supports the full order lifecycle, from pre-dispatched to dispatched statuses, enabling adaptability across various workflows.

  • Multi-Provider Integration: - Efficiently retrieve and evaluate delivery 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 delivery 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?

Once set up as a user, you can submit relevant order details to asynchronously place an order from the selected pickup location to the delivery address. By integrating this API into your eCommerce platform, you gain access to a global multi-carrier ecosystem. This enables you to offer flexible, reliable delivery options while maintaining control over your brand’s delivery experience.

FAQs

  • What information does a Delivery Order contain?

    A Delivery Order contains all the critical details needed to execute a delivery, such as pickup and delivery addresses, contact information, and scheduling preferences.

  • What happens when an order is submitted?

    When a delivery order request is submitted, the platform fetches delivery estimates from integrated providers and applies configurable orchestration rules to select the most appropriate provider, ensuring efficiency and a high level of customer satisfaction.

  • Pre-Dispatched vs Dispatched Status

    Pre-Dispatched orders are present on the platform but have not yet been shared with a provider. Dispatched orders have been assigned to a provider for fulfillment.

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.

/deliveries

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 Field validation failed 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.

/deliveries/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

/deliveries/{delivery_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 Resource 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 Resource not found: 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 Field validation failed: packages parameter cannot be changed post order dispatch or any other invalid value
NOT_FOUND 404 Hard Resource not found: 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.
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.

/deliveries/{delivery_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

/deliveries/{delivery_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 Resource not found: 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 Delivery

This endpoint enables clients to asynchronously create a new delivery order. Its primary function is to initiate a delivery request by submitting the required details for processing. The operation is designed to be asynchronous, meaning the initial response will include only basic metadata about the order. Subsequent status updates and detailed progress information are sent through Webhooks configured by the client.

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

version

Value: "v1"
Request Body schema: application/json
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 delivery 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 each package in the packages array.

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.

Array of objects (Package) <= 50 items

Array of packages included in the delivery order. Each package contains an itemList property that references items from the order itemList by SKU. The quantity of each item within a package must not exceed the total quantity provided for that item in the itemList.

Array (<= 50 items)
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.

object (Weight)

Weight of an item

quantity
integer <int32> >= 1

Number of Packages

itemQuantity
integer <int32> >= 1

Number of items in a single package.

Array of objects (Item) <= 1000 items

Array of items in the package.

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 packages

signature
string <= 100 characters

Indicates whether a signature is required for the delivery. 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)

tips
number >= 0

Driver tip in major units as a decimal, e.g. 9.00 ($9.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

Responses
201

Resource is successfully created

400

The request cannot be processed due to incompleteness or invalid data

401

Unauthorized

422

Processing failed as request contains invalid data

500

Internal server error

post/delivery/{version}/deliveries
Request samples
application/json
{
  • "locationExternalId": "7709",
  • "orderExternalId": "7709-001",
  • "orderValue": 10,
  • "tips": 2,
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "packages": [
    ],
  • "itemList": [],
  • "pickupTime": null,
  • "deliveryTime": null
}
Response samples
application/json
{
  • "locationExternalId": "7709",
  • "orderExternalId": "7709-001",
  • "orderValue": 10,
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "packages": [
    ],
  • "itemList": [],
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "orderAttributes": { },
  • "tenantId": "dummyaccount1",
  • "brandExternalId": "dummyaccount1",
  • "groupId": null,
  • "currencyCode": "USD",
  • "pickupContact": {
    },
  • "pickupAddress": {
    },
  • "status": "REQUEST_RECEIVED",
  • "referenceLinks": {
    },
  • "provider": {
    },
  • "trackingId": "",
  • "attachments": null,
  • "driver": null,
  • "vehicle": null,
  • "amount": null,
  • "labels": null,
  • "tips": null,
  • "actualDeliveryTime": null,
  • "actualPickupTime": null,
  • "fee": null,
  • "returnRequest": null,
  • "proposedProviders": [ ],
  • "providerBatch": null,
  • "createdAt": "",
  • "lastUpdatedAt": "",
  • "undeliverableOrderReturnLocation": {
    },
  • "returnLocationId": "301",
  • "deliveryDistance": 2,
  • "drivingDistance": 3
}

List Deliveries

Use this endpoint to retrieve a filtered list of deliveries based on specified criteria. By default, if no filters are applied, deliveries created within the last 24 hours will be returned.

This API supports advanced filtering options such as:

  • Time Filters: Filter deliveries based on their createdAt, pickupTime, deliveryTime, or lastUpdatedAt.

  • Identifiers: Search by orderExternalIds or locationExternalIds.

  • Statuses: Retrieve deliveries based on their current status (e.g., ORDER_DISPATCHED, ORDER_DELIVERED, ORDER_CANCELLED).

  • Pagination: Use the paginationToken field to retrieve subsequent sets of results when dealing with large datasets.

The request body allows flexible and precise filtering, making it easy to tailor the response to your specific needs. The response will contain the requested delivery data, and if applicable, a paginationToken to fetch additional results.

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/delivery/{version}/deliveries/list
Request samples
application/json
{
  • "limit": 100,
  • "lastUpdatedAt": {
    },
  • "orderExternalIds": [
    ],
  • "locationExternalIds": [
    ],
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "createdAt": {
    },
  • "status": [
    ],
  • "paginationToken": "NjI2N2M5YWIwM2FiNjQ5NDdjYWZiYmMxXzYyNjdjOWFiMDNhYjY0OTQ3Y2FmYmJjMV82MjY3Y2FkNzYyN2Y1ZjY1OGM4YjljNTNfbmV4dA=="
}
Response samples
application/json
{
  • "data": [
    ]
}

Get Delivery

Use this API to retrieve detailed information about a specific delivery order using its delivery_id. By default, the response provides the most recently cached data about the delivery. To fetch the latest information directly from the delivery provider and bypass the cache, set the force_update query parameter to true.

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

version

Value: "v1"
delivery_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 delivery, this field should be assigned true

Responses
200

Request was successful

401

Unauthorized

404

Resource was not found

422

Processing failed as request contains invalid data

500

Internal server error

get/delivery/{version}/deliveries/{delivery_id}
Request samples 
Response samples 
application/json
{
  • "id": "5e1f1ef5167ab20010a74b94",
  • "brandExternalId": "demoBrand",
  • "locationExternalId": "NYClocation101",
  • "orderExternalId": "876581",
  • "groupId": "group1",
  • "orderValue": 11,
  • "tips": 2,
  • "itemList": [ ],
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "packages": [
    ],
  • "deliveryInstructions": "Some text for delivery instructions",
  • "orderAttributes": {
    },
  • "estimatedDeliveryTime": {
    },
  • "estimatedPickupTime": {
    },
  • "labels": 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 Delivery
Use this API to cancel an existing delivery order identified by its delivery_id. This operation ensures the order is canceled in both Delivery Solutions' system and the provider's system; however, the ability to cancel depends on the provider's stipulations. Ensure that the provided delivery_id matches the ID returned during order creation to successfully process the cancellation and update all relevant systems.


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


 Value: "v1"  
delivery_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
Processing failed as request contains invalid data


500
Internal server error


delete/delivery/{version}/deliveries/{delivery_id}
Request samples 
Response samples 
application/json
{
  • "id": "62a9e3ce87f3c9df15080f00",
  • "estimatedDeliveryTime": {
    },
  • "estimatedPickupTime": {
    },
  • "referenceLinks": {},
  • "provider": {
    },
  • "amount": null,
  • "locationExternalId": "100983",
  • "orderExternalId": "15June11",
  • "groupId": null,
  • "orderValue": 78.65,
  • "tips": 8,
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "proposedProviders": [
    ],
  • "signature": "not_required",
  • "packages": [
    ],
  • "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",
  • "deliveryDistance": 2,
  • "drivingDistance": 3
}
Edit Delivery
Use this API to modify the details of the delivery after it has been placed in our system.


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


 Value: "v1"  
delivery_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 delivery edit operation this field should be assigned true.


 
Request Body schema: application/json
orderExternalId
string  <= 100 characters 
Client-side identifier for the delivery 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 delivery 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 each package in the packages array.


 
 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.


 
Array of objects (Package)   <= 50 items 
Array of packages included in the delivery order.
Each package contains an itemList property that references items from the order itemList by SKU.
The quantity of each item within a package must not exceed the total quantity provided for that item in the itemList.


 
 Array (<= 50 items)
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.


 
object (Weight) 
Weight of an item


 
quantity
integer <int32>   >= 1 
Number of Packages


 
itemQuantity
integer <int32>   >= 1 
Number of items in a single package.


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


 
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 packages


 
signature
string  <= 100 characters 
Indicates signature requirement


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


 
orderValue
number  >= 0 
Total value of the order


 
tips
number  >= 0 
Driver tip in major units as a decimal, e.g. 9.00 ($9.00 USD).


 
locale
string  <= 5 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/delivery/{version}/deliveries/{delivery_id}
Request samples 
application/json
{
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "packages": [
    ],
  • "orderExternalId": "19082413",
  • "orderValue": 160.99
}
Response samples 
application/json
{
  • "id": "5e1f1ef5167ab20010a74b94",
  • "brandExternalId": "Demobrand",
  • "itemList": [ ],
  • "locationExternalId": "NYClocation101",
  • "orderExternalId": "876581",
  • "groupId": "group1",
  • "orderValue": 11,
  • "tips": 2,
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    },
  • "packages": [
    ],
  • "deliveryInstructions": "Some text for delivery instructions",
  • "orderAttributes": {
    },
  • "estimatedDeliveryTime": {
    },
  • "estimatedPickupTime": {
    },
  • "labels": 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 Delivery Status
Use this API to retrieve the complete status history of a delivery order, including timestamps, identified by its delivery_id.
The status history provides a detailed chronological log of all status changes throughout the delivery lifecycle. Optionally, you can use the is_unique query parameter to retrieve only unique statuses.


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


 Value: "v1"  
delivery_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
boolean
Return only unique delivery status progressions (true or false).


 
 Example:  is_unique=false
Responses 
200
Request was successful


401
Unauthorized


500
Internal server error


get/delivery/{version}/deliveries/{delivery_id}/status-history
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retry Delivery
Use this API to manually retry the delivery dispatch process for a specific delivery order that previously failed. This endpoint is particularly useful in cases where a delivery failure occurred due to issues such as an invalid address or missing details. Once the necessary corrections have been made, you can use this API to initiate the dispatch process again.


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


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


 
 Example:  60b8d6c9e4b0f5d3a1a6e500
Responses 
201
Delivery retry successful


401
Unauthorized


404
Resource was not found


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


422
Processing failed as request contains invalid data


500
Internal server error


post/delivery/{version}/deliveries/{delivery_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,
  • "driver": null,
  • "vehicle": null,
  • "labels": null,
  • "pickupInstructions": "Enter from the staff entrance to pick up the package",
  • "deliveryContact": {
    },
  • "packages": [
    ],
  • "pickupAddress": {
    },
  • "deliveryAddress": {
    },
  • "tips": null,
  • "proposedProviders": [ ],
  • "groupId": null,
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "deliveryDistance": 2,
  • "drivingDistance": 3,
  • "lastUpdatedAt": "2020-01-15T14:17:25.984Z",
  • "createdAt": "2020-01-15T14:17:25.984Z"
}
➔ Next to Eligibility