📘

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

Buy with Prime enables you to accelerate your e-commerce business by offering Prime shopping benefits on your site. To interact with Buy with Prime 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.

With the Buy with Prime API, you can populate your Buy with Prime catalog with products, display estimated delivery information to shoppers throughout their journey across your site, create and query Buy with Prime orders, sync refunds and returns with data in your system, and so on.

This guide describes direct integration with the Buy with Prime API. Alternatively, you can offer Buy with Prime on your site in the following ways:

• Buy with Prime app for Shopify: You can offer Buy with Prime on your Shopify site by installing the Buy with Prime app in your Shopify Admin. For details, see Buy with Prime App for Shopify.
• Buy with Prime for Salesforce Commerce Cloud: You can offer Buy with Prime on your Salesforce Commerce Cloud site by installing the Buy with Prime cartridge in your Business Manager. For details, see Buy with Prime for Salesforce Commerce Cloud.
• Add the Buy with Prime widget to your site: You can add a Buy with Prime button to your site by using a code snippet that you generate in the Buy with Prime merchant console. For details, see Buy with Prime Widget.

How the Buy with Prime API works

With GraphQL APIs, you send requests that contain queries and mutations to an API endpoint over HTTPS. Queries request data, whereas mutations change data. For Buy with Prime, you make the following requests to the Buy with Prime GraphQL endpoint:

• Queries: You send queries to request data from Buy with Prime. For example, you use the deliveryPreview query to return information, such as the delivery date range, that you can display alongside Buy with Prime products on your site. The following figure shows a product detail page that displays information returned by the deliveryPreview query.

• Mutations: You send mutations to change data in your Buy with Prime account. For example, to create an order, you call the createOrder mutation.

As part of the GraphQL query or mutation, you specify the fields that you want the API to return. For example, if you want information about refunds related to an order, you can call the order query and specify that you only want fields from the refunds object.

Buy with Prime interfaces group queries and mutations that relate to the same concept. Examples of interfaces include the Catalog interface, Order interface, Delivery Preview interface, and so on. For a list of Buy with Prime interfaces, see Buy with Prime interfaces.

Buy with Prime publishes events when the state of underlying resources change. For example, a DELIVERY_COMPLETED event is published when one or more items are delivered to their destination, a RETURN_STARTED event is published when a shopper starts a return, and so on. You can subscribe to events by using the Event Interface.

Some Buy with Prime queries and mutations take (or require) a shopper's Amazon identity token. The identity token enables you to customize the Buy with Prime experience to the shopper on your site, such as display information based on whether the shopper is a Prime member, pre-populate a shipping address at checkout, and provide more accurate delivery estimates on product detail pages. To get an identity token, you can use Login with Amazon (LWA) or Amazon Pay.

Both identity approaches (LWA and Amazon Pay) enable shoppers to sign in using their Amazon account credentials, but the approaches differ in terms of checkout flow and which payment options are available to the shopper:

• LWA: If you Use Login with Amazon for Shopper Identity, you own payment processing completely so that your shoppers can use any payment options, such as digital wallets, that your site supports.
• Amazon Pay: If the only payment option that you want to support is Amazon Pay, you can Use Amazon Pay for Shopper Identity and use an Amazon Pay checkout session token to identify the shopper.

Prerequisites

To use Buy with Prime, your organization must have the following prerequisites:

• Your own e-commerce site.
• A professional Seller Central account or an Amazon Supply Chain account.
• A Buy with Prime account. For information about the Buy with Prime account associated with your site, see your e-commerce manager.

Using the Buy with Prime API

The following figure provides a high-level overview of how you interact with the Buy with Prime API during runtime. You authenticate to the Buy with Prime API through standard OAuth2.0 flows.

Before runtime, you must get your API credentials from the Buy with Prime merchant console. For details, see Generate API credentials.

The figure shows the following interactions:

• You send a request to the Buy with Prime API: Assemble a query or mutation for the Buy with Prime functionality that you want to access. To find the available queries and mutations, you can browse the developer guides and API reference documentation in the left sidebar of this documentation. The developer guides and API reference documentation provide sample requests and responses that you can reference when you write your code. For example, you can find Catalog interface examples, Order interface examples, Delivery Preview interface examples, and so on.

• You receive a response from the Buy with Prime API: The Buy with Prime API returns a response that contains the fields that you specified in your request. Parse the responses and take the appropriate action on your site.

• Changes in Buy with Prime resources trigger events: When Buy with Prime resources change, they can trigger events. Examples of events are INVENTORY_CHANGED, DELIVERY_IN_TRANSIT, and so on. You subscribe to events by using the Buy with Prime API Event interface. For instructions on how to subscribe to events, see Steps to Subscribe to Buy with Prime Events. For a list of events, see Event Types. Buy with Prime events are represented as JSON objects that all have a similar structure. When you receive an event, parse the events and update your downstream systems. For details about how to handle events, see the documentation for individual event types.

Get started

To make your first call to the Buy with Prime GraphQL API, take the following steps:

1. Get your Buy with Prime API credentials: You generate your API credentials within the Buy with Prime merchant console. For details, see Generate API credentials.
2. Get an access token: To get an access token, call the Buy with Prime token endpoint with the API credentials you got in the previous step. For details, see Use API credentials to get an access token.
3. Call the GraphQL API: When you have an access token, you can call the GraphQL API. For details, see Call the Buy with Prime API.

After you are able to call the API, review Steps to Integrate with Buy with Prime to see an overview of the integration steps.

Related topics

• Call the Buy with Prime API
• Authenticate to the Buy with Prime API
• Terminology