j1.1.0
API Overview
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 (
productIdscurrently 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.estimatehook 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-idheader for easier production troubleshooting.
Related APIs
This API is commonly used with SLAS token APIs for shopper authentication and Shopper Products APIs for PDP data retrieval.
Let us know so we can improve!