Create Delivery Previews
Important
The Buy with Prime API is offered as a preview and might change as we receive feedback and iterate on the interfaces. We are sharing this early documentation to help you learn about the Buy with Prime API as we write and iterate on the content.
The Buy with Prime Delivery Preview interface enables you to display estimated delivery information to shoppers throughout their journey across your site. You can use this interface to get delivery previews for products that are eligible for Buy with Prime.
For example, delivery previews can provide the following information on product detail pages and checkout pages:
- Product detail pages: When the shopper's location is unknown, delivery previews provide an estimated delivery date. If the shopper signs in with their Amazon credentials (for example, using a delivery card), delivery previews calculate a delivery date based on their saved address.
- Checkout pages: When the shopper's address is available through Amazon Wallet or entered directly during the checkout process, delivery previews calculate a delivery date based on the address.
To formulate a delivery preview, Amazon's fulfillment systems optimize combinations of requested products in requested quantities with the amount of inventory available across the Amazon Fulfillment Network.
The shopper typically sees the delivery preview as a message that appears with the Prime badge in purchase and checkout experiences.
Buy with Prime Delivery Preview
In this topic, we first present terminology related to delivery previews, cross-referencing the terms to their associated programming constructs in the Buy with Prime GraphQL API. We then provide a list of operations that you can use to work with delivery previews.
For example requests and responses, see Delivery Preview Interface Examples.
Terminology
The following figure shows an overview of the elements associated with a Buy with Prime delivery preview.
Each delivery preview contains one or more DeliveryGroup objects, which are collections of products that will be packed and delivered together in a shipment along with the relevant delivery offers available for the group.
The following sections describe the elements and match each element to its programming construct. We group the concepts into delivery preview inputs and outputs.
Inputs
To generate a delivery preview, you provide the following information to the Delivery Preview interface. For a full list of fields in the delivery preview input, see DeliveryPreviewInput.
Delivery terms input
| Description | Context that you provide to the deliveryPreview query. Delivery terms are fundamental in shaping the outcome of the API response. You can provide the isPrimeEligible flag to denote 1) whether you offer Buy with Prime for the product and 2) whether the product is buyable. |
| Associated programming construct | DeliveryTermsInput, which you specify in the DeliveryItemInput to the deliveryPreview query. The isPrimeEligible field is a Boolean. |
| Notes | The
To return only Prime offers, set |
Identity token
| Description | Amazon shopper token that enables the Delivery Preview interface to provide a more accurate delivery preview for the shopper. |
| Associated programming construct | IdentityTokenInput |
| Notes | Buy with Prime currently supports two types of identity tokens as the IdentityTokenInput: Login with Amazon (LWA) access tokens and Amazon Pay checkout session tokens. |
Item identifier
| Description | Identifier for a Buy with Prime product. Includes Buy with Prime-generated item IDs, Amazon SKUs, and external platform IDs. Item identifiers enable you to customize your Buy with Prime integration based on your catalog's unique requirements. |
| Associated programming construct | ProductIdentifierInput, which you specify in DeliveryProductInput to the deliveryPreview query. |
| Notes | N/A |
Location
| Description | The delivery location, which allows for granularity in options such as IP address, zip code, and shipping address. |
| Associated programming construct | DeliveryLocationInput, which you specify in DeliveryItemInput to the deliveryPreview query. |
| Notes | Delivery location contributes significantly to the accuracy, confidence level, and latency of the returned delivery offers. The more shopper and delivery information that you provide in the API request, the higher the confidence level of the offer returned. Higher specificity comes with higher latency. When you use the |
Outputs
Delivery previews contain the following information. For a full list fields in the delivery preview output, see DeliveryPreview.
Delivery group
| Description | A collection of products that will be packed and delivered together in a shipment, along with the relevant delivery offers available for the group. For a delivery preview with multiple products, each item can only be a part of one valid delivery group; multiple items can be in a single delivery group. |
| Associated programming construct | DeliveryGroup, which is nested in the response from the deliveryPreview query. |
| Notes | N/A |
Delivery offer
| Description | Delivery options that you can show to shoppers. Encapsulates information like delivery date range, messaging, and the Prime logo. |
| Associated programming construct | DeliveryOffer, one or more of which are in a DeliveryGroup. Â Â Â Â Â Â Â Â |
| Notes | N/A |
Delivery preview
| Description | Delivery preview information organized into delivery groups, which are collections of products that will be packed and delivered together in a shipment along with the relevant delivery offers available for the group. |
| Associated programming construct | DeliveryPreview, which is returned from a query to deliveryPreview. |
| Notes | The more precise shopper context you provide in the call to deliveryPreview, the more accurate the result. |
Delivery term
| Description | Contains the following information about the delivery terms for a given delivery group:
|
| Associated programming construct | DeliveryTerms, which is nested in a DeliveryGroup in a deliveryPreview. The isPrimeEligible flag is a Boolean. DeliverySpeed is a string. |
| Notes | DeliverySpeed returns only delivery offers for products that aren't eligible for Buy with Prime. |
Offer expiry
| Description | Offer is valid until this timestamp. Applies only to authenticated shoppers who have provided a complete address. For unauthenticated shoppers, where the zip code or IP address serves as a proxy for location, this attribute returns null, because offer expiry does not apply to their experience. If the offer for authenticated shopper is expired, to generate a new offer, call the delivery preview API. |
| Associated programming construct | expiresAt , which you specify in DeliveryOffer |
| Notes | N/A |
API operations
The Buy with Prime Delivery Preview interface supports the following mutations, queries, and events.
Mutations
None.
Queries
| Name | Description |
|---|---|
deliveryPreview | Returns the delivery offers for a list of items. |
shopperBwPEligibility | Returns the Prime membership status for the shopper. |
Events
None.
Where to start
To display a delivery preview, call the deliveryPreview query. For example requests and responses, see Delivery Preview Interface Examples.
Related topics
Updated about 17 hours ago