API Reference | ReDoc

Provider Rates and Availability

Product Info

The Provider Rates and Availability API allows applications to retrieve and evaluate service rates, availability, and estimated delivery times from logistics providers while leveraging orchestration capabilities to prioritize options, apply business rules, and determine service feasibility between shipping and delivery locations.

Business Values

  • Dynamic Rate Retrieval: - Retrieve service rates, availability, and estimated delivery times from multiple logistics providers, empowering businesses to make informed decisions tailored to specific delivery needs.

  • Orchestration Integration: - Apply customizable business rules to prioritize rate options based on organizational objectives, ensuring the selection of optimal service providers.

  • Scalability and Flexibility: - Support up to 10 shipping locations per rate request, enabling efficient handling of multiple store locations with minimal latency.

  • Enhanced Accuracy: - Leverage package dimensions, weight, and item details for precise rate calculations, ensuring competitive and accurate service estimates.

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

Once set up as a user, you can submit relevant order details, including the pickup location and delivery address, to retrieve rates and estimated delivery times from multiple providers. By integrating this API into your platform, you gain dynamic rate calculation and orchestration capabilities. This allows for seamless optimization of delivery costs and services while maintaining operational efficiency.

FAQs

  • What are the minimum required parameters?

    • Configured shipping provider within the portal.
    • zipcode in deliveryAddress.
    • storeExternalIds to identify the shipping locations.

  • What does the rates response include?

    The response includes service rates and estimated pickup/delivery times from multiple providers, along with errors and validation messages if a provider cannot fulfill the request.

  • What is the role of packages and itemList?

    These provide dimensions, weight, and item details to calculate accurate rates and optimize post-purchase experiences.

  • How does orchestration affect rate selection?

    If orchestration rules are applied, the selected rates are flagged (ruleApplied: true) in the response. To filter only the winning rates, set the displayWinningRates parameter to true.

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.

/rates

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 422 Hard Invalid data: No such locationExternalId exists in our system or other invalid values in the request
INVALID_DATA 400 Hard Invalid data: Missing required fields (e.g., deliveryAddress) or other invalid values in the request
VALIDATION_ERROR 400 Hard Field validation failed as per the expected input.
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.

Retrieve Rates, Estimated Times, and Service Availability

When placing an order with any Provider, the estimated pickup and delivery times along with the rate provided by each service offered by the Provider are crucial information that can help in deciding the Provider and the services offered by it. The Get Rates API helps achieve this for all the Providers assigned to the locations.

The minimum required parameters for the Rate API are postalCode in the deliveryAddress and the locationExternalIds. This provides the rates for all the Providers assigned to the locations for delivery to a location in that postalCode.

The Rate API comes with the ability to use Orchestration. If the orchestration module is used, then the ruleApplied is set to true on the rates which are selected by the orchestration module. By default, all the rates processed by the orchestration module are sent in the response. The API can be configured to send only those rates that are selected by the orchestration module and filter the rest by setting the displayWinningRates parameter to true.

The default options for the get rates can also be configured at the business level. Please contact Delivery Solutions Support if you wish to configure the default options for the Rates Request API. The configured default options can be overridden while using the API.

The rate response provides an array of rates - each rate consisting of the estimated pick up and delivery time offered by different services of the Providers along with the amounts that it shall charge for the service. The response also includes errors sent by the Provider if the provider is unable to provide a rate for the given parameters as well as any validation messages.

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

version

Value: "v1"
Request Body schema: application/json
required
object (schemas-Address)

Address of the location

street1
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"
number or null
Any of:
number
longitude
number <double>

Longitude coordinates of the address

locationExternalIds
required
Array of strings <= 5 items

Array of Unique Id of the pickup locations.

type
string

This field is used to indicate preferred fulfillment type. If delivery/pickup/shipping are provided as the type, the system will provide rates to only those Providers that matches the type. If type is not specified, all available fulfilment options will be considered for rates.

Enum: "delivery" "shipping" "pickup"
orderValue
number <float> >= 0

Value of the order in dollars & cents. e.g., 10.00 or 116.50.

TimingWindow (object) or null
One of:
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)

TimingWindow (object) or null
One of:
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)

object

Override default configured rate options set for the business.

allowOrchestration
boolean

If this option is set to true then rates will be sent to the orchestration engine, which will filter the rates according to the orchestration rules.

displayWinningRates
boolean

This option decides whether to send all the rates or to send only the rates selected by the orchestration engine.

Array of objects (components-schemas-Package) <= 50 items

Array of packages included in the 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 (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

Array of objects (components-schemas-Item) <= 100 items

Array of items included in the 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.

category
string <= 100 characters

Category of Item

upc
string <= 100 characters

Universal Product Code for the 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

Additional information related to the item.

matchProviderTags
Array of strings

Rates for providers matching at least one tag from the requested tags are returned.

orderAttributes
object

Configurable key-value pairs of custom order attributes.

matchLocationTags
Array of strings

Rates for locations matching at least one tag from the requested location tags are returned.

proposedProviders
Array of objects

Override orchestration and get rates with the specified Provider and Service.

object
property name*
additional property
any
Responses
200

Request was successful

400

Bad Request

401

Unauthorized

422

Processing failed as request contains invalid data

500

Internal server error

post/rate/{version}/rates
Request samples
application/json
{
  • "type": "delivery",
  • "locationExternalIds": [
    ],
  • "deliveryAddress": {
    }
}
Response samples
application/json
{
  • "rates": [
    ],
  • "errors": [ ],
  • "rateId": "62b1e1682810e724d36595ab"
}
➔ Next to Returns