Use the Shopper Delivery Estimates API to retrieve carrier-calculated delivery date ranges for a single product at a destination postal code. The API is intended for product detail pages (PDP) where shoppers want to know when an item will arrive before adding it to a basket.

For the requested product, the platform enumerates the site's applicable shipping methods. Estimates are returned only when the sfcc.app.shipping.estimate hook is bound to a provider via an installed Commerce App; if no provider is bound, the platform returns no estimates.

The Shopper Delivery Estimates API is currently uncached. The URL is deterministic in productIds, postalCode, and countryCode, and will utilize a cache layer in the future.

Authentication & Authorization

The Shopper Delivery Estimates API requires a shopper access token.

For details on how to request an access token, see Get a Shopper Token from SLAS.

You must include sfcc.shopper-delivery-estimates and sfcc.shopper-standard in the client ID used to generate the token. For a full list of permissions, see the Authorization Scopes Catalog.

Customization

Hooks

For details on working with hooks, see Extensibility with Hooks.

Response Details

Personalization

Responses from this API are not personalized via the Shopper Context API.

Caching

Responses from this API are not cached. The endpoint is currently uncached even though request URLs are deterministic for productIds, postalCode, and countryCode; a cache layer is planned for a future release. For details, see Server-Side Web-Tier Caching.

Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see Timeouts and Limits.

Error Handling

Error responses follow the RFC 7807 problem detail format. To trace errors, include a correlation-id header in your request — the response returns it as x-correlation-id. For details, see HTTP Status Codes and Errors.

Use Cases

Show "Arrives by" on a Product Detail Page

Use this API on the PDP after a shopper enters postal code and country. The response provides delivery windows by applicable shipping method so you can display messaging such as "Arrives Fri, Oct 4."

curl -X GET \
"https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-delivery-estimates/v1/organizations/{organizationId}/delivery-estimates?siteId={siteId}&productIds={productId}&postalCode=94105&countryCode=US" \
-H "Authorization: Bearer {shopper_access_token}" \
-H "Content-Type: application/json" \
-H "correlation-id: pdp-delivery-estimate-001"

Choose Which Shipping Methods to Highlight

The response includes one entry per applicable shipping method for each product. If a method is deliverable, use the deliveryWindow; if it is not deliverable, use nonDeliverableReason to suppress or de-prioritize that method in your UI.

Hide the Estimate Module When No Estimates Are Available

If productDeliveryEstimates is empty, no estimates are available for requested products (for example, no applicable shipping methods or no provider response). In that case, hide the delivery estimate component to avoid showing incomplete or misleading delivery messaging.

Best Practices

Keep calls scoped to PDP interactions, since the endpoint is currently uncached.
Respect the current one-product constraint (productIds currently supports one product per request) and avoid batching assumptions until multi-product support is released.
Gracefully handle partial availability by rendering only methods with delivery windows and clearly handling non-deliverable methods.
Ensure the sfcc.app.shipping.estimate hook is bound to a provider via an installed Commerce App — without a bound provider, no estimates are returned. Validate hook performance and timeout behavior to stay within the 10-second Shopper API limit.
Always include a correlation-id header for easier production troubleshooting.

This API is commonly used with SLAS token APIs for shopper authentication and Shopper Products APIs for PDP data retrieval.*

Simple example:

  import { ShopperDeliveryEstimates } from "commerce-sdk-isomorphic";

  const clientConfig = {
    parameters: {
      clientId: "XXXXXX",
      organizationId: "XXXX",
      shortCode: "XXX",
      siteId: "XX"
    }
  };
  const shopperDeliveryEstimatesClient = new ShopperDeliveryEstimates(clientConfig);

API Version: 0.0.33
Last Updated:

Type parameters

ConfigParameters: ShopperDeliveryEstimatesParameters & Record<string, unknown>

Hierarchy

ShopperDeliveryEstimates

Index

Constructors

constructor

Properties

Methods

getDeliveryEstimates

Object literals

apiPaths

Constructors

constructor

new ShopperDeliveryEstimates(config: ClientConfigInit<ConfigParameters>): ShopperDeliveryEstimates

- Defined in src/lib/shopperDeliveryEstimates/apis/DefaultApi.ts:170
Parameters
- config: ClientConfigInit<ConfigParameters>
Returns ShopperDeliveryEstimates

Properties

clientConfig

clientConfig: ClientConfig<ConfigParameters> & { baseUri: string }

Static Readonly defaultBaseUri

defaultBaseUri: "https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-delivery-estimates/v1" = currentBaseUri

Static Readonly paramKeys

paramKeys: { getDeliveryEstimates: ["organizationId", "productIds", "postalCode", "countryCode", "siteId", "personalized"]; getDeliveryEstimatesRequired: ["organizationId", "productIds", "postalCode", "countryCode", "siteId"] } = {getDeliveryEstimates: ['organizationId','productIds','postalCode','countryCode','siteId','personalized',],getDeliveryEstimatesRequired: ['organizationId','productIds','postalCode','countryCode','siteId',],} as const

Type declaration

getDeliveryEstimates: ["organizationId", "productIds", "postalCode", "countryCode", "siteId", "personalized"]
getDeliveryEstimatesRequired: ["organizationId", "productIds", "postalCode", "countryCode", "siteId"]

Methods

getDeliveryEstimates

getDeliveryEstimates(options?: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ countryCode: string; organizationId: string; personalized?: GetDeliveryEstimatesPersonalizedEnum; postalCode: string; productIds: Array<string>; siteId: string } & QueryParameters, ConfigParameters> }>): Promise<DeliveryEstimatesResult>
getDeliveryEstimates<T>(options?: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ countryCode: string; organizationId: string; personalized?: GetDeliveryEstimatesPersonalizedEnum; postalCode: string; productIds: Array<string>; siteId: string } & QueryParameters, ConfigParameters> }>, rawResponse?: T): Promise<T extends true ? Response : DeliveryEstimatesResult>

- Defined in src/lib/shopperDeliveryEstimates/apis/DefaultApi.ts:216
Returns delivery date estimates for the requested products at a destination postal code. Currently limited to one product per request. For each requested product, the platform enumerates all applicable site-level shipping methods. Estimates are returned only when the sfcc.app.shipping.estimate Commerce Apps hook is bound to a provider. If no provider is bound, the platform returns no estimates. Each entry in the response corresponds to one requested product, and contains one entry per applicable shipping method. Methods for which the provider returned an estimate carry a deliveryWindow. Methods for which the provider could not return an estimate include a nonDeliverableReason. An empty productDeliveryEstimates array means the platform has no estimates for any of the requested products, for example, no applicable shipping methods or the provider returned no results. In this case, clients should hide the delivery estimation block.

If you would like to get a raw Response object use the other getDeliveryEstimates function.

Parameters
- Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ countryCode: string; organizationId: string; personalized?: GetDeliveryEstimatesPersonalizedEnum; postalCode: string; productIds: Array<string>; siteId: string } & QueryParameters, ConfigParameters> }>
  
  An object containing the options for this method.
Returns Promise<DeliveryEstimatesResult>

A promise of type DeliveryEstimatesResult.
- Defined in src/lib/shopperDeliveryEstimates/apis/DefaultApi.ts:247
Returns delivery date estimates for the requested products at a destination postal code. Currently limited to one product per request. For each requested product, the platform enumerates all applicable site-level shipping methods. Estimates are returned only when the sfcc.app.shipping.estimate Commerce Apps hook is bound to a provider. If no provider is bound, the platform returns no estimates. Each entry in the response corresponds to one requested product, and contains one entry per applicable shipping method. Methods for which the provider returned an estimate carry a deliveryWindow. Methods for which the provider could not return an estimate include a nonDeliverableReason. An empty productDeliveryEstimates array means the platform has no estimates for any of the requested products, for example, no applicable shipping methods or the provider returned no results. In this case, clients should hide the delivery estimation block.

Type parameters
- T: boolean
Parameters
- Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ countryCode: string; organizationId: string; personalized?: GetDeliveryEstimatesPersonalizedEnum; postalCode: string; productIds: Array<string>; siteId: string } & QueryParameters, ConfigParameters> }>
  
  An object containing the options for this method.
- Optional rawResponse: T
  
  Set to true to return entire Response object instead of DTO.
Returns Promise<T extends true ? Response : DeliveryEstimatesResult>

A promise of type Response if rawResponse is true, a promise of type DeliveryEstimatesResult otherwise.

Object literals

Static Readonly apiPaths

apiPaths: object

getDeliveryEstimates

getDeliveryEstimates: string = "/organizations/{organizationId}/delivery-estimates"

Shopper Delivery Estimates

API Overview

Authentication & Authorization

Customization

Hooks

Response Details

Personalization

Caching

Timeouts

Error Handling

Use Cases

Show "Arrives by" on a Product Detail Page

Choose Which Shipping Methods to Highlight

Hide the Estimate Module When No Estimates Are Available

Best Practices

Related APIs

Type parameters

ConfigParameters: ShopperDeliveryEstimatesParameters & Record<string, unknown>

Hierarchy

Index

Constructors

Properties

Methods

Object literals

Constructors

constructor

Parameters

config: ClientConfigInit<ConfigParameters>

Returns ShopperDeliveryEstimates

Properties

clientConfig

Static Readonly defaultBaseUri

Static Readonly paramKeys

Type declaration

getDeliveryEstimates: ["organizationId", "productIds", "postalCode", "countryCode", "siteId", "personalized"]

getDeliveryEstimatesRequired: ["organizationId", "productIds", "postalCode", "countryCode", "siteId"]

Methods

getDeliveryEstimates

Parameters

Returns Promise<DeliveryEstimatesResult>

Type parameters

T: boolean

Parameters

Optional rawResponse: T

Returns Promise<T extends true ? Response : DeliveryEstimatesResult>

Object literals

Static Readonly apiPaths

getDeliveryEstimates