Buy with Prime | Developer Documentation
Documentation

Call the Buy with Prime API

📘

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

To interact with Buy with Prime data programmatically, you use the Buy with Prime GraphQL API. GraphQL is a query language for APIs, as well as a runtime for fulfilling those queries. This topic shows you how to format requests to the Buy with Prime API, how to parse responses, and how to handle errors.

Before you read this topic, we recommend that you familiarize yourself with the basics of GraphQL. For information about GraphQL, see the GraphQL documentation.

Prerequisites

Before you call the Buy with Prime API, you must generate your Buy with Prime API credentials and use the API credentials to get an access token.

Making a request

A GraphQL request is an HTTPS POST request to a specific endpoint, with the content of the body changing between requests. The endpoint for the Buy with Prime API is https://api.buywithprime.amazon.com/graphql.

Request header

The following example shows a header for a request to the Buy with Prime API.

POST /graphql HTTP/1.1
Host: api.buywithprime.amazon.com
Authorization: Bearer EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN
Content-Type: application/json
x-api-target-id: EXAMPLE_TARGET_ID
x-api-version: $api_version

The request header contains the following parameters.

ParameterDescriptionTypeRequired
AuthorizationA bearer token that you retrieve by making an HTTPS POST request to the Buy with Prime API token endpoint (https://api.buywithprime.amazon.com/token). For details about how to make this request, see Use API credentials to get an access token.StringYes
x-api-target-idThe business product ID for the business product instance with which you are interacting. This is the TargetId from the API credentials that you downloaded in Generate API credentials.StringYes
x-api-version

The Buy with Prime API version number in ISO 8601 date format (YYYY-MM-DD).

Examples: 2024-04-01 and 2024-01-01.

StringYes

Request body

The body of a GraphQL query is a structured object that specifies the data that you want the API to return. The data object in the response will be structured almost identically to the request structure.

The body of the request depends on the schema of the interface that you are calling and which data in that schema you want the Buy with Prime API to return. The developer guides in the Buy with Prime API documentation contain examples of requests and responses based on the schema of the associated interface.

Example requests

The following examples show requests to the deliveryPreview query:

In the examples, replace the following values:

  • Replace EXAMPLE_TARGET_ID with the TargetId from the API credentials that you downloaded in Generate API credentials.
  • Replace EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN with a bearer token returned by an HTTPS POST request to the Buy with Prime API token endpoint. For details about how to make this request, see Use API credentials to get an access token.
  • Replace EXAMPLE_ITEM_ID with an ExternalId of a product. (For details on product IDs, see ItemIdentifierInput.)

Complete request example

The following is an example of a complete request to the deliveryPreview query.

POST /graphql HTTP/1.1
Host: api.buywithprime.amazon.com
Content-Type: application/json
x-api-target-id: EXAMPLE_TARGET_ID
x-api-version: $api_version
Authorization: Bearer EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN 

{
   "query": "query {\n deliveryPreview(\n  input: {\n items: [\n  {\n itemIdentifier: { \n ExternalId: \"EXAMPLE_ITEM_ID\" \n }\n quantity: { \n unit: \"UNIT\"\n amount: 1\n }\n }\n \n ]\n }\n ) {\n  id\n deliveryGroups {\n id\n deliveryOffers {\n policy {\n messaging {\n messageText\n locale\n badge\n }\n }\n }\n }\n }\n}\n"
}

curl --location --request POST 'https://api.buywithprime.amazon.com/graphql' \
--header 'Content-Type: application/json' \
--header 'x-api-target-id: EXAMPLE_TARGET_ID' \
--header 'x-api-version: $api_version' \
--header 'Authorization: Bearer EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN' \
--data-raw '{
   "query": "query {\n deliveryPreview(\n  input: {\n items: [\n  {\n itemIdentifier: { \n ExternalId: \"EXAMPLE_ITEM_ID\" \n }\n quantity: { \n unit: \"UNIT\"\n amount: 1\n }\n }\n \n ]\n }\n ) {\n  id\n deliveryGroups {\n id\n deliveryOffers {\n policy {\n messaging {\n messageText\n locale\n badge\n }\n }\n }\n }\n }\n}\n"
}'

import requests
import json
url = "https://api.buywithprime.amazon.com/graphql"

headers = {
  'Content-Type': 'application/json',
  'x-api-target-id': 'EXAMPLE_TARGET_ID',
  'x-api-version': '$api_version',  
  'Authorization': 'Bearer EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN'
}

payload = """
{
  deliveryPreview(
    input: {
      items: [
        {
          itemIdentifier: {
            ExternalId: "EXAMPLE_ITEM_ID"
          }
          quantity: {
            unit: "UNIT"
            amount: 1
          }
        }
      ]
    }
  ) {
  id
  deliveryGroups {
    id
    deliveryOffers {
      policy {
        messaging {
          messageText
          locale
          badge
        }
      }
    }
  }
 }
}
"""
response = requests.request("POST", url, headers=headers, json={"query": payload})
print(response.text)

const url = "https://api.buywithprime.amazon.com/graphql";
const headers = {
  "Content-Type": "application/json",
  "Accept": "application/json",
  "x-api-target-id": "EXAMPLE_TARGET_ID",  
  "x-api-version": "$api_version",  
  "Authorization": "bearer " + "EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN"
};

const query = `query {
  deliveryPreview(
    input: {
      items: [
        {
          itemIdentifier: {
            ExternalId: "EXAMPLE_ITEM_ID"
          }
          quantity: {
            unit: "UNIT"
            amount: 1
          }
        }
      ]
    }
  ) {
  id
  deliveryGroups {
    id
    deliveryOffers {
      policy {
        messaging {
          messageText
          locale
          badge
        }
      }
    }
  }
 }
}`;

fetch(url, {
  method: "POST",
  headers: headers,  
  body: JSON.stringify({
    query
  })
}).then(response => {
    return response.json();
}).then(json => {
  console.log(JSON.stringify(json)); 
});

Complete request example with variables

If you want to use the same query with different inputs, you can use variables. You prefix variables in the query with a dollar sign ($). The following example shows the previous JavaScript query using variables for the input.

const url = "https://api.buywithprime.amazon.com/graphql";
const headers = {
  "Content-Type": "application/json",
  "Accept": "application/json",
  "x-api-target-id": "EXAMPLE_TARGET_ID",  
  "x-api-version": "$api_version",  
  "Authorization": "bearer " + "EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN"
};

const query = `
  query deliveryPreview($input: DeliveryPreviewInput!) {
    deliveryPreview(input: $input) {
    id
    deliveryGroups {
      id
      deliveryOffers {
        policy {
        messaging {
          messageText
          locale
          badge
        }
      }
    }
  }
 }
}`;

const variables = {
  input: {
    items: [
      {
        itemIdentifier: {
          ExternalId: "EXAMPLE_ITEM_ID"
        },
        quantity: {
          unit: "UNIT",
          amount: 1
        }
      }
    ]
  }
};

fetch(url, {
  method: "POST",
  headers: headers,  
  body: JSON.stringify({
    query,
    variables
  })
}).then(response => {
    return response.json();
}).then(json => {
  console.log(JSON.stringify(json)); 
});

Complete request example with a shopper identity token

Some Buy with Prime queries and mutations optionally take (or require) a shopper's Amazon identity token so that the operations can return responses specific to the shopper. For example, you can provide a more accurate delivery preview if you provide the optional IdentityTokenInput field. For details about which shopper identity tokens Buy with Prime supports, see Amazon identity token.

The following example shows how to create a delivery preview with the shopper's Amazon identity token. In the body of the request, shopperIdentity is the object in which you supply an identifier that uniquely identifies a shopper's session in your integration's session management system.

POST /graphql HTTP/1.1
Host: api.buywithprime.amazon.com
Content-Type: application/json
x-api-target-id: EXAMPLE_TARGET_ID
x-api-version: $api_version
Authorization: Bearer EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN

{
   "query": "query {\n deliveryPreview(\n input: {\n items: [\n {\n itemIdentifier: { \n ExternalId: \"EXAMPLE_ITEM_ID\" \n }\n quantity: { \n unit: \"UNIT\"\n amount: 1\n }\n }\n \n ]\n terms: {\n shopperIdentity: {\n lwaAccessToken: {\n externalId: \"EXAMPLE_EXTERNAL_ID\"\n value: \"EXAMPLE_LWA_ACCESS_TOKEN\"\n  }\n  }\n }\n  }\n ) {\n  id\n deliveryGroups {\n id\n deliveryOffers {\n policy {\n messaging {\n  messageText\n locale\n badge\n }\n  }\n  }\n  }\n }\n}\n"
}

curl --location --request POST 'https://api.buywithprime.amazon.com/graphql' \
--header 'Content-Type: application/json' \
--header 'x-api-target-id: EXAMPLE_TARGET_ID' \
--header 'x-api-version: $api_version' \
--header 'Authorization: Bearer EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN' \
--data-raw '{
   "query": "query {\n deliveryPreview(\n input: {\n items: [\n {\n itemIdentifier: { \n ExternalId: \"EXAMPLE_ITEM_ID\" \n }\n quantity: { \n unit: \"UNIT\"\n amount: 1\n }\n }\n \n ]\n terms: {\n shopperIdentity: {\n lwaAccessToken: {\n externalId: \"EXAMPLE_EXTERNAL_ID\"\n value: \"EXAMPLE_LWA_ACCESS_TOKEN\"\n  }\n  }\n }\n  }\n ) {\n  id\n deliveryGroups {\n id\n deliveryOffers {\n policy {\n messaging {\n  messageText\n locale\n badge\n }\n  }\n  }\n  }\n }\n}\n"
}'

import requests
import json
url = "https://api.buywithprime.amazon.com/graphql"

headers = {
  'Content-Type': 'application/json',
  'x-api-target-id': 'EXAMPLE_TARGET_ID',
  'x-api-version': '$api_version',  
  'Authorization': 'Bearer EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN'
}

payload = """
{
  deliveryPreview(
    input: {
      items: [
        {
          itemIdentifier: {
            ExternalId: "EXAMPLE_ITEM_ID"
          }
          quantity: {
            unit: "UNIT"
            amount: 1
          }
        }
      ]
      terms: {
        shopperIdentity: {
           lwaAccessToken: {
            externalId: "EXAMPLE_EXTERNAL_ID"
            value: "EXAMPLE_LWA_ACCESS_TOKEN"
           }
        }
      }    
    }
  ) {
  id
  deliveryGroups {
    id
    deliveryOffers {
      policy {
        messaging {
          messageText
          locale
          badge
        }
      }
    }
  }
 }
}
"""

response = requests.request("POST", url, headers=headers, json={"query": payload})
print(response.text)

const url = "https://api.buywithprime.amazon.com/graphql";
const headers = {
  "Content-Type": "application/json",
  "Accept": "application/json",
  "x-api-target-id": "EXAMPLE_TARGET_ID",  
  "x-api-version": "$api_version",  
  "Authorization": "bearer " + "EXAMPLE_BUY_WITH_PRIME_ACCESS_TOKEN"
};

const query = `query {
    deliveryPreview(
        input: {
            items: [
                {
                    itemIdentifier: {
                        ExternalId: "EXAMPLE_ITEM_ID"
                    }
                    quantity: {
                        unit: "UNIT"
                        amount: 1
                    }
                }
            ]
        terms: {
        shopperIdentity: {
           lwaAccessToken: {
            externalId: "EXAMPLE_EXTERNAL_ID"
            value: "EXAMPLE_LWA_ACCESS_TOKEN"
           }
        }
        }
        }
    ) {
        id
        deliveryGroups {
            id
            deliveryOffers {
                policy {
                    messaging {
                        messageText
                        locale
                        badge
                    }
                }
            }
        }
    }
}`;

fetch(url, {
  method: "POST",
  headers: headers,  
  body: JSON.stringify({
    query
  })
}).then(response => {
    return response.json();
}).then(json => {
  console.log(JSON.stringify(json)); 
});

Note that the previous example uses an LWA access token as the shopper's identity token. To use an Amazon Pay checkout session as the shopper's identity token, replace the following part of the previous example:

terms: {
    shopperIdentity: {
        lwaAccessToken: {
            externalId: "EXAMPLE_EXTERNAL_ID",
            value: "EXAMPLE_LWA_ACCESS_TOKEN"
         }
    }
}

with:

terms: {
    shopperIdentity: {
        apayCheckoutSessionId: {
            externalId: "EXAMPLE_EXTERNAL_ID",
            value: "EXAMPLE_CHECKOUT_SESSION_ID"
        }
    }
}

Parsing the response

The body of a response from the Buy with Prime API is a JSON object in the following format.

{
  "data": {
    // The fields you requested to be returned in the GraphQL API call 
  },
  "errors": [ ... ]
}

The response body contains either a data object, an errors object, or both.

ParameterDescriptionType
dataThe response data based upon the fields you requested in your query.Object
errorsA list of any errors that occurred while processing your query. For details, see Handling errors.Array of objects

The following example shows what a response to the deliveryPreview query might look like based on the fields the query requested.

{
  "data": {
    "deliveryPreview": {
      "id": "EXAMPLE_DELIVERY_PREVIEW_ID",
      "deliveryGroups": [
        {
          "id": "EXAMPLE_DELIVERY_GROUP_ID",
          "deliveryOffers": [
            {
              "policy": {
                "messaging": {
                  "messageText": "Get it as soon as Fri, Feb 23",
                  "locale": "en-US",
                  "badge": "PRIME"
                }
              }
            }
          ]
        }
      ]
    }
  }
}

For the field descriptions, see DeliveryPreview in the Buy with Prime API reference.

It's possible for both data and errors objects to be present when the query was partially processed successfully and was valid, but some field of the query might have failed. For example, you might fetch the information for a product including price and inventory, but the inventory node might have failed to process due to a service issue. The response returns the price data, and the inventory field is null. In the errors list, you will find an error associated with the inventory.

Handling errors

Per the GraphQL specification, the Buy with Prime API always returns a 200 status OK for all responses, even if those responses contain errors. If the errors array is present in the response, iterate through the errors array to evaluate the errors. The errors might indicate a need to retry after a particular delay, an error in the Buy with Prime service, an invalid input, or a bug in your code.

If you receive an error with an HTTP status code other than 200, it’s likely that the Buy with Prime API never received your request. For example, there might be an issue with your network. You should implement a simple retry strategy for these errors.

Error structure

If present, the errors object in a response from the Buy with Prime API has the following structure.

{
  "errors": [
    {
      "message": "Example error message.",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "title"
      ],
      "extensions": {
        "classification": {
          "type": "ValidationError",
          "code": "InputMaxLength",
          "details": {
            // Schema specific to the interface.
          }
        }
      }
    }
  ],
  "data": null
}

Error parameters

The errors object contains the following pieces of information that you can use for debugging.

ParameterDescriptionType
messageA human-readable message to help with debugging. We don't recommend that you write error-handling logic based on this message, because it might change.String
locationsThe character location where the error was encountered. This information is intended for debugging and not recommended for error-handling logic.Array of objects
pathThe field where the error occurred, including all parent objects that were being resolved during the error.Array of strings
extensionsA type and code that you can use for managing error handling.Object

Error types

When you use the Buy with Prime API, you can encounter the following types of errors. For details about how to handle errors in the context of a specific Buy with Prime interface, see the troubleshooting topic for that interface. For example, for the Catalog interface, see Troubleshoot Catalog Errors.

Error TypeDescriptionSuggested Action
AccessDeniedErrorYou don't have sufficient access to perform this action. This could be because your API credentials are missing the appropriate permission scopes, your access token expired, or you don't own the requested resource.Ensure that your API credentials have the permission scope that the operation requires. For details, see Authenticate to the Buy with Prime API. The required permission scope is listed at the top of the API documentation for each query and mutation. (For example, the required scope for the deliveryPreview query is "View Delivery Preview.") Generate a new API credential client with the correct permissions, retrieve a new access token, and then retry the call.
InternalServerErrorUnexpected error during request processing. This is a server-side error.If the error is retriable, the response includes a Retry-After header. If the Retry-After header isn't present, you shouldn't retry. In addition, we recommend that you not retry a request more than once, even if the Retry-After header is present on the retried request response.
ResourceNotFoundErrorThe resource you're trying to access doesn't exist.In the majority of cases, you shouldn't retry this request. However, if you just created the resource, there's a possibility that retrying the request will succeed.
ThrottlingErrorYou tried to access a resource at too high a frequency. There are many different aspects to throttling, and you might find that the throttling limits for one resource are different to another.Send the request again using exponential backoff. You can also check the response's Retry-After header, which indicates when to retry.
ValidationErrorThe data you provided in the request is invalid.Retrying the request with the same data isn't going to succeed. This error indicates that you might need to fix your data, or address an underlying problem in your code. A ValidationError is accompanied by a code field that indicates the nature of the validation error so that you can make in code branching decisions on how to handle these types of errors.

Related topics

Updated 3 days ago