API Reference | ReDoc

Eligibility

Product Info

The Eligibility API provides tools to enhance logistics operations, including delivery coverage checks, smart window configurations, and address confidence scoring. It is designed to integrate seamlessly with various provider services and supports customizable orchestration rules for tailored responses.

Business Values

  • Delivery Assurance: - determines if a customer's address is covered by any locations as well as provides available fulfillment methods that the customer is eligible for.
  • Smart Windows: - returns available windows that take into account store timings as well as pick and pack time so that a customer can select their preferred window.
  • Address Confidence: - This provides a confidence score for a specified drop-off address in the ability to deliver an order. This allows a business to determine if they will deliver there or may need to require insurance for the order.

FAQs

  • Should I use the customers full address or can I just use the zip code in the Delivery Coverage request?

    The more address information you provide, the more accurate the response is — so the full address will be the most accurate.

If you are using the full address, you can turn on caching in the business settings.

  • What if I use only the zip code in the Delivery Coverage request?

    For a zip code only request, we find an address around the center of the zip code to use for the request. If the customers final address is on the far end of the zip code from the store, there is the potential the added distance means they are no longer in a serviceable boundary once the order is placed and dispatched.

  • How is the delivery coverage determined?

    The delivery coverage can be requested at the store boundary, DSP, or store boundary + DSP level.

  • Can I retrieve the providers windows instead of the store windows with the Smart Windows call?

    Yes, you can use the "provider" option in the call to return the providers available windows.

  • How many days of windows can I retrieve?

    The API provides up to 7 days of time windows

  • Where can I configure my businesses windows?

    Time windows can be configured at the Business, Brand, or Location level.

  • Is a higher or lower confidence score better?

    The higher the confidence score, the more confidence we have in the delivery of the order. So the higher the score the better.

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.

/smart-windows

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 exist or other invalid values in the request
NOT_FOUND 404 Hard Resource Not Found: Location Timings Not found
TOO_MANY_REQUESTS 429 Transient Too many requests received per second.
UNMAPPED_ERROR 422 Transient Request received unidentifiable error response.

/coverage/{services}

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: Delivery Address Not Provided 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.

/confidence-score/{logistics_type}

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: Delivery Address Not Provided 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 Available Time Windows

The Smart Windows API allows customers to view configurable time windows for pick-up or delivery based on the specified category, date, and location. This API supports configurations for pick-and-pack lead times, packing times, and associated capacities and costs. Time windows can be configured at the Business, Brand, or Location level, and the API provides up to 7 days of time windows. Optionally, the request can include a provider name to retrieve provider-specific time windows. Note that location timings must be configured before retrieving provider-specific windows.

Each time window takes into account:

  • Lead Time: The preparation time required before an item can be picked.
  • Packing Time: The time needed to pack an order.

This API enables flexible scheduling by providing a tailored view of available time windows, helping customers select suitable options for their operational needs.

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

version

Value: "v1"
Request Body schema: application/json
locationExternalIds
required
Array of strings

Array of locationExternalId. One or many Location Ids for which delivery timings are to be returned.

categories
Array of strings

Categories of windows to return. Defaults to all categories.

startDate
string <date>

Baseline date from which numberOfDays to be calculated. ISO 8601 Calendar Date (YYYY-MM-DD) as per location’s timezone. Defaults to current date.

numberOfDays
integer <int32>

Non-zero positive integer indicating how many days of windows to return. Defaults to 1.

providerCheck
boolean
Default: false

Flag to indicate if the system should intelligently check top and bottom windows of each day to ensure providers availability for the start and end. Uses location’s address/postalcode for the check against the providers. Default is false.

types
Array of strings
Default: ["delivery"]

Type of window timings. Options are pickup, delivery, or return. Defaults to type delivery.

provider
string

Windows will be retrieved from the requested provider instead of matching windows configured at our end.

object (Options)

Override default configured options.

Array of objects (ItemForSmartWindows)
Array
quantity
required
integer <int32> >= 1

Number of items. Defaults to 1.

object (Size)

Dimensions of the item.

required
object (Weight)

Weight of an item

Responses
200

Request was successful

401

Unauthorized

404

Resource was not found

422

Processing failed as request contains invalid data

500

Internal server error

post/eligibility/{version}/smart-windows
Request samples
application/json
{
  • "locationExternalIds": [
    ],
  • "startDate": "2025-01-01",
  • "numberOfDays": 2,
  • "types": [
    ],
  • "categories": [
    ],
  • "providerCheck": false
}
Response samples
application/json
{
  • "message": "success",
  • "data": [
    ]
}

Check Coverage Eligibility

This endpoint verifies delivery coverage for the requested services. The available services include:

  • Location Coverage: Determines if the delivery address falls within the coverage area of any location and returns a list of locations that can service the address.

  • Provider Coverage: Checks if at least one provider associated with a location offers delivery coverage.

  • Location + Provider Coverage: Provides a combined check for both location and provider coverage.

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

version

Value: "v1"
services
required
string

The service type to check coverage for.

Enum: "provider-coverage" "location-coverage" "location-provider-coverage"
Request Body schema: application/json
locationExternalId
string <= 100 characters

Required when utilising provider service. If locationExternalId is provided for location-coverage service, the location boundary check will be limited to that location.

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

matchBoundaryTags
Array of strings

Match locations whose boundaries have at least one of the tags (eg: "tags":["sdd","fleet"]) that are passed in an array and cover the dropoff address.

matchProviderTags
Array of strings

All the providers matching at least one tag are returned. This is only available for the provider and location-provider-coverage services.

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)

sortByDistance
boolean

When true, it returns all the locations that cover the deliveryAddress sorted in the ascending order by distance.

object

Fetches the nearest locations that serve the deliveryAddress for a given radius. When this field is provided, the coverage boundaries associated with the locations are ignored. This is only available for the location-coverage and location-provider-coverage services.

radius
required
number <float>

The radius (in miles) within which the locations need to be searched for.

count
integer <int32>

Limit the Number of locations in the response. locations are first sorted by distance i.e nearest appears first in list, and then limited by count.

showFulfillmentOptions
boolean

When true, it returns the order type and provider services supported by the location.

bypassCache
boolean

If caching is enabled in the business profile to reduce latency, customers can bypass the cache for this API by including bypassCache set to true in their request

matchLocationTags
Array of strings

All the locations matching at least one tag are returned. This is only available for the location-coverage and location-provider-coverage services.

Responses
200

Request was successful

400

Bad Request

401

Unauthorized

500

Internal server error

post/eligibility/{version}/coverage/{services}
Request samples
application/json
{
  • "deliveryAddress": {
    }
}
Response samples
application/json
{
  • "locationCoverage": {
    }
}

Check Confidence Score

This endpoint provides a confidence score for a specified drop-off address. The logistics_type parameter specifies the type of logistics (e.g., forward).

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

version

Value: "v1"
logistics_type
required
string

The type of logistics (e.g., forward).

Value: "forward"
Request Body schema: application/json
required
object (ConfidenceScoreAddress)

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 <= 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

bypassCache
boolean

If caching is enabled in the business profile to reduce latency, customers can bypass the cache for this API by including bypassCache set to true in their request

Responses
200

Request was successful

204

No confidence score is available. The request was processed successfully, but no content is available to return due to insufficient historical data.

400

Bad Request

401

Unauthorized

500

Internal server error

post/eligibility/{version}/confidence-score/{logistics_type}
Request samples
application/json
{
  • "deliveryAddress": {
    }
}
Response samples
application/json
{
  • "confidenceScore": {
    }
}
➔ Next to Location Management