Buy with Prime | Developer Documentation
Documentation

Create a Delivery Preview for a Product Detail Page

📘

Buy with Prime API is now available for early access

Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.

Sign Up

This topic contains examples of requests and responses that show how to use the Buy with Prime Delivery Preview interface to get a delivery preview that you can display on a product detail page.

Delivery Preview on a Product Detail Page

Delivery Preview on a Product Detail Page

The examples are ordered such that they use and display an increasing amount of shopper data to refine the delivery estimates. Shopper data can be obtained from shopper input on your site or from a shopper’s Amazon account (if they're signed in). While increasing the amount of shopper data provides a more accurate delivery estimate, it can also increase the latency of the API call.

To learn how to call the Buy with Prime API, see Call the Buy with Prime API.

Sample data

The examples in this topic use the following sample data.

Sample catalog data 
val inSearchOfLostTime = {
    title: "In Search of Lost Time",
    isbn: "example-isbn",
    isPrimeIntended: true,
    sku: "example-sku",
    mSku: "example-msku",
    imageUrl: "https://example.com/images/example-image.jpg",
    detailPageUrl: "https://www.amazon.com/dp/example-detail-page-1"
};

Create a delivery preview with no shopper data or delivery location information

In the simplest case, you can get a delivery offer by providing only product information, and no additional shopper or delivery details. The following query is the easiest to construct and the least accurate for a given shopper.

Request 
// Variables from sample data
inSearchOfLostTime

// GraphQL query
query deliveryPreview($input: DeliveryPreviewInput!) {
    deliveryPreview(input: $input) {
      id
      deliveryGroups {
        id
        deliveryOffers {
          id
          date {
            earliest
            latest
          }
          policy {
            messaging {
              messageText
              locale
              badge
            }
          }
          expiresAt
        }
      }
   }
}

// Query variables
{
  "input": {
     "products": [
      {
        "productIdentifier": {
           "SKU": inSearchOfLostTime.sku
          },
        "amount": {
          "unit:" "UNIT",
          "value": 1
        }
      }
    ]
  }
}
Response 
{
  "data":{
    "deliveryPreview":{
      "id":"example-delivery-preview-id",
      "deliveryGroups":[
        {
          "id":"example-delivery-group-id",
          "deliveryOffers":[
            {
              "id":"example-delivery-offer-id",
              "date":{
                "earliest":"2023-12-07T04:00:00Z",
                "latest":"2023-12-07T04:00:00Z"
              },
              "policy":{
                "messaging":{
                  "messageText":"Get it as soon as Tomorrow Dec 6",
                  "locale":"en-US",
                  "badge":"PRIME"
                }
              },
              "expiresAt":null
            }
          ]
        }
      ]
    }
  }
}

Create a delivery preview with the shopper's IP address

If you have access to the shopper's IP address, you can enhance delivery offers by using geolocation data associated with the IP address. This scenario relies on the current virtual location of the shopper and tends to be more accurate than creating a delivery preview with no shopper data.

Request 
# Variables from sample data
inSearchOfLostTime

// GraphQL query
query deliveryPreview($input: DeliveryPreviewInput!) {
    deliveryPreview(input: $input) {
      id
      deliveryGroups {
        id
        deliveryOffers {
          id
          date {
            earliest
            latest
          }
          policy {
            messaging {
              messageText
              locale
              badge
            }
          }
          expiresAt
        }
      }
   }
}

// Query variables
{
  "input": {
     "products": [
      {
        "productIdentifier": {
          "SKU": inSearchOfLostTime.sku
        },
        "amount": {
          "unit:" "UNIT",
          "value": 1
        }
      }
    ],
    "terms": {
      "location": {
        "ipAddress": "192.0.2.0",
      }
    }
  }
}
Response 
{
  "data":{
    "deliveryPreview":{
      "id":"example-delivery-preview-id",
      "deliveryGroups":[
        {
          "id":"example-delivery-group-id",
          "deliveryOffers":[
            {
              "id":"example-delivery-offer-id",
              "date":{
                "earliest":"2023-12-08T04:00:00Z",
                "latest":"2023-12-08T04:00:00Z"
              },
              "policy":{
                "messaging":{
                  "messageText":"Get it as soon as Thu, Dec 7",
                  "locale":"en-US",
                  "badge":"PRIME"
                }
              },
              "expiresAt":null
            }
          ]
        }
      ]
    }
  }
}

Create a delivery preview with the shopper's postal code

If you have access to the shopper's postal code, you can refine delivery offers by using geolocation data associated with the postal code. A shopper can provide their postal code either indirectly through their signed-in identity, or directly through an experience on the product detail page, which allows postal code input. In either case, this scenario provides a highly accurate delivery estimate because it requires additional context about the shopper.

For example, if the shopper signs in with their Amazon account credentials and enters a zip code on your website, you can pass both the shopper identity and the zip code to the deliveryPreview query so that the returned delivery preview is specific to the zip code as the delivery location.

Request 
# Variables from sample data
inSearchOfLostTime

// GraphQL query
query deliveryPreview($input: DeliveryPreviewInput!) {
    deliveryPreview(input: $input) {
      id
      deliveryGroups {
        id
        deliveryOffers {
          id
          date {
            earliest
            latest
          }
          policy {
            messaging {
              messageText
              locale
              badge
            }
          }
          expiresAt
        }
      }
    }
  }

// Query variables
{
   "input": {
      "products": [
       {
        "productIdentifier": {
          "SKU": inSearchOfLostTime.sku
        },
        "amount": {
          "unit:" "UNIT",
          "value": 1
        }
      }
    ],
    "terms": {
      "location": {
        "shippingAddress": {
           "postalCode": "98109"
        }
      }
    }
  }
}
Response 
{
  "data":{
    "deliveryPreview":{
      "id":"example-delivery-preview-id",
      "deliveryGroups":[
        {
          "id":"example-delivery-group-id",
          "deliveryOffers":[
            {
              "id":"example-delivery-offer-id",
              "date":{
                "earliest":"2023-12-07T04:00:00Z",
                "latest":"2023-12-07T04:00:00Z"
              },
              "policy":{
                "messaging":{
                  "messageText":"Get it as soon as Tomorrow Dec 6",
                  "locale":"en-US",
                  "badge":"PRIME"
                }
              },
              "expiresAt":null
            }
          ]
        }
      ]
    }
  }
}

Create a delivery preview with the shopper's delivery address

For more accurate and detailed delivery offers, you can include the shopper's complete delivery address. A shopper can provide their delivery address either indirectly through their identity (if they're signed in), or directly by choosing their delivery location on a product detail page. In either case, this scenario provides the most accurate delivery estimate because it requires the most context about the shopper.

Request 
# Variables from sample data
inSearchOfLostTime

// GraphQL query
query deliveryPreview($input: DeliveryPreviewInput!) {
    deliveryPreview(input: $input) {
      id
      deliveryGroups {
        id
        deliveryOffers {
          id
          date {
            earliest
            latest
          }
          policy {
            messaging {
              messageText
              locale
              badge
            }
          }
          expiresAt
        }
      }
    }
  }

// Query variables
{
  "input": {
    "products": [
      {
        "productIdentifier": {
          "SKU": inSearchOfLostTime.sku
        },
        "amount": {
          "unit:" "UNIT",
          "value": 1
        }
      }
    ],
    "terms": {
      "location": {
        "shippingAddress": {
          "name": "John Doe",
          "streetAddress": "410 Terry Ave N",
          "locality": "Seattle",
          "region": "WA",
          "postalCode": "98109",
          "countryCode": "US"
        }
      }
    }
  }
}
Response 
{
  "data":{
  "deliveryPreview":{
    "id":"example-delivery-preview-id",
    "deliveryGroups":[
      {
        "id":"example-delivery-group-id",
        "deliveryOffers":[
          {
            "id":"example-delivery-offer-id",
            "date":{
              "earliest":"2023-12-07T04:00:00Z",
              "latest":"2023-12-07T04:00:00Z"
            },
            "policy":{
              "messaging":{
                "messageText":"Get it as soon as Tomorrow Dec 6",
                "locale":"en-US",
                "badge":"PRIME"
              }
            },
            "expiresAt":null
          }
        ]
      }
    ]
  }
}

Create a delivery preview with the shopper's Amazon identity

If the shopper is identified through their shopper identity token, the delivery preview can be tailored to surface delivery offers based on their Amazon account information.

If the shopper signs in with their Amazon account credentials but provides no other delivery location preferences for you to pass to the deliveryPreview query, the returned delivery preview is based on the default address in the shopper's address book.

Request 
# Variables from sample data
inSearchOfLostTime

// GraphQL query
query deliveryPreview($input: DeliveryPreviewInput!) {
    deliveryPreview(input: $input) {
      id
      deliveryGroups {
        id
        deliveryOffers {
          id
          date {
            earliest
            latest
          }
          policy {
            messaging {
              messageText
              locale
              badge
            }
          }
          expiresAt
        }
      }
    }
  }

// Query variables
{
  "input": {
    "products": [
      {
        "productIdentifier": {
          "SKU": inSearchOfLostTime.sku
        },
        "amount": {
          "unit:" "UNIT",
          "value": 1
        }
      }
    ],
    "terms": {
      "shopperIdentity": {
        "lwaAccessToken":{
          "value": "EXAMPLE_LWA_ACCESS_TOKEN",
          "externalId": "EXAMPLE_EXTERNAL_ID"
        }
      }
    }
  }
}
Response 
{
  "data":{
  "deliveryPreview":{
    "id":"example-delivery-preview-id",
    "deliveryGroups":[
      {
        "id":"example-delivery-group-id",
        "deliveryOffers":[
          {
            "id":"example-delivery-offer-id",
            "date":{
              "earliest":"2023-12-07T04:00:00Z",
              "latest":"2023-12-07T04:00:00Z"
            },
            "policy":{
              "messaging":{
                "messageText":"Get it as soon as Tomorrow Dec 6",
                "locale":"en-US",
                "badge":"PRIME"
              }
            },
            "expiresAt":null
          }
        ]
      }
    ]
  }
}

Related topics

Updated 23 days ago