API Reference | ReDoc

Tracker

Product Info

The Tracker API allows businesses to create trackers for orders not dispatched through our API Solutions, enabling use of post-purchase and returns features.

Business Values

  • Post-Purchase Management: - The post-purchase experience encompasses timely alerts, notifications, and user-friendly tracking pages, helping customers stay informed about their order's journey.

  • Returns Module: - Streamline the process for customers to initiate returns and exchanges efficiently.

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

Once you are set up as a user, you can submit existing order details, including the carrier's tracking number, to facilitate a seamless post-purchase and returns experience based on the portal's configuration. The API will then respond with the appropriate links for customers to access these features.

FAQs

  • What is required for the difference between an order and a tracker?

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

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.

/trackers:

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_TRACKER_DATA 422 Hard Invalid data: This provider is not configured in corporate or other invalid values in the request
MISSING_TRACKER_DATA 400 Hard Invalid data: Delivery Address not provided or other invalid values in the request

Create Tracker

This endpoint allows businesses to create a tracker using the tracking number provided by the carrier. Trackers enable a unified post-purchase experience for all orders, including alerts, notifications, and tracking pages. To create a tracker, the carrier must be configured for the business, and a valid tracking number is required.

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

version

Value: "v2"
Request Body schema: application/json
locationExternalId
string <= 100 characters

locationExternalId of the pickup location. Either locationExternalId or pickup is mandatory.

trackingId
string <= 100 characters

Tracking Id given by the carrier

type
string <= 100 characters

Tracker type. Options are delivery/ pickup/ shipping. Defaults to shipping.

Enum: "pickup" "delivery" "shipping"
groupId
string or null <= 100 characters

Group ID allows you to group a number of orders and trackers together. It further helps in providing a combined post-purchase experience for them.

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
orderValue
number <double> >= 0

Value of the order in major units as decimals. e.g., 10.00 or 116.50.

components-schemas-TimeWindow (object) or null

Time Window in which the package will be ready to be picked up. null defaults to ASAP.

One of:

Time Window in which the package will be ready to be picked up. null defaults to ASAP.

startsAt
integer or null <int64>

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

endsAt
integer or null <int64>

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

components-schemas-TimeWindow (object) or null

Time Window in which the package must be delivered by. null defaults to ASAP. Not needed for pickup type of tracker.

One of:

Time Window in which the package must be delivered by. null defaults to ASAP. Not needed for pickup type of tracker.

startsAt
integer or null <int64>

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

endsAt
integer or null <int64>

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

object (components-schemas-Customer)

Customer information.

name
required
string <= 100 characters

First Name of Contact

phone
required
string <= 20 characters

Phone Number of the Contact

email
string <= 100 characters

Email address of the Contact

userExternalId
string <= 100 characters

External Id assigned to customer

object (Tracker-API_components-schemas-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
required
string <= 100 characters

City

state
required
string [ 2 .. 100 ] characters

The ISO 3166-2 country or territory code

postalCode
required
string <= 20 characters

Postal code or zip.

countryCode
string = 2 characters ^[A-Z]{2}
Default: "US"

The ISO 3166 country or territory code

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 instruction for the location. This will override the instructions configured with the pickup location.

deliveryInstructions
string or null <= 10000 characters

Delivery instructions for drop-off.

Array of objects (Tracker-API_components-schemas-Package)
Array
name
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 (schemas-Size)

Dimensions of the item.

object (schemas-Weight)

Weight of an item

quantity
integer <int32> >= 1
Default: 1

Number of Packages

itemQuantity
integer <int32> >= 1
Default: 1

Number of items in a single package.

Array of objects (Tracker-API_components-schemas-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

trackerExternalId
string <= 100 characters

Unique Id of the tracker generated in your system and configured in our system, has to be unique.

barcodes
Array of strings

Barcodes sent to the provider for scanning the packages

createdDate
integer <int64>

Date at which the order was originally created in Unix time in milliseconds

Array of objects (Tracker-API_components-schemas-Item)
Array
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

Universal Product Code for the item

quantity
integer <int32> >= 1

Number of items of the SKU

object (schemas-Size)

Dimensions of the item.

object (schemas-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.

object

Custom item attributes.

tags
Array of strings

Additional information related to the item.

locale
string = 5 characters ^[a-z]{2}-[A-Z]{2}$

Comprised of the ISO 639 language code and the ISO 3166 country code separated by a dash.

object

Information about the pickup. Either locationExternalId or pickup is mandatory.

name
required
string <= 100 characters

Name of the pickup location.

brandExternalId
string <= 100 characters

Brand under which the pickup location will be created. Defaults to default brand.

locationExternalId
string <= 100 characters

Unique ID of the pickup location generated in your system and configured in our system.

object (Tracker-API_components-schemas-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
required
string <= 100 characters

City

state
required
string [ 2 .. 100 ] characters

The ISO 3166-2 country or territory code

postalCode
required
string <= 20 characters

Postal code or zip.

countryCode
string = 2 characters ^[A-Z]{2}
Default: "US"

The ISO 3166 country or territory code

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 pickup location.

Array of objects (Provider)

List of providers configured for the pickup location.

Array
name
string or null <= 100 characters

Provider name

object (components-schemas-Contact)

Customer information.

name
required
string <= 100 characters

First Name of Contact

phone
required
string <= 20 characters

Phone Number of the Contact

email
string <= 100 characters

Email address of the Contact

object

Dynamic key-value pairs for provider attributes

property name*
additional property
string or integer or number or boolean or null <= 100 characters
provider
string <= 100 characters

Name of the provider configured in business

Responses
201

Success

400

Bad Request

401

Unauthorized

422

Unprocessed Entity

500

Internal Server Error

post/tracker/{version}/trackers
Request samples
application/json
{
  • "provider": "Self Delivery",
  • "locationExternalId": "Self Delivery Store",
  • "trackerExternalId": "tracker001",
  • "trackingId": "del_004",
  • "barcodes": [
    ],
  • "type": "delivery",
  • "orderAttributes": { },
  • "orderValue": 100,
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "deliveryContact": {
    },
  • "deliveryAddress": {
    }
}
Response samples
application/json
{
  • "locationExternalId": "Postmates_Store",
  • "trackingId": "del_004",
  • "brandExternalId": "trackers_business",
  • "orderExternalId": "tracker001",
  • "packages": [ ],
  • "type": "delivery",
  • "orderAttributes": { },
  • "orderValue": 100,
  • "status": "ORDER_DISPATCHED",
  • "pickupTime": {
    },
  • "deliveryTime": {
    },
  • "estimatedPickupTime": {
    },
  • "estimatedDeliveryTime": {
    },
  • "tips": null,
  • "lastLocation": null,
  • "driver": null,
  • "vehicle": null,
  • "provider": {
    },
  • "currencyCode": "USD",
  • "deliveryAddress": {
    },
  • "deliveryContact": {
    },
  • "deliveryInstructions": null,
  • "pickupInstructions": "location pickupInstructions",
  • "groupId": null,
  • "timeZone": "America/Chicago",
  • "pickupContact": {
    },
  • "pickupAddress": {
    },
  • "id": "62a051c1729b5dfcdeae1870",
  • "referenceLinks": {},
  • "trackerExternalId": "tracker001",
  • "source": {
    }
}
➔ Next to OAuth Client Credentials