📘
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 Order interface enables you to create and query Buy with Prime orders. You can use Buy with Prime for multiple stages of the shopping experience. To use Buy with Prime, you must use Amazon for fulfillment.

In this topic, we first present terminology related to orders, 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 orders.

For example requests and responses, see Order interface examples.

Terminology

The following figure shows some of the elements associated with a Buy with Prime order. Dashed lines show line item associations and solid lines indicate elements associated with the overall order.

You can specify most entities at both the order level and line-item level. Also, due to the presence of both Details and Summary fields, you can provide as much or as little information as you want to provide.

Note: We strongly recommend that you specify any monetary charges on the order, such as discounts or taxes, at the line-item level for accurate Prime fee computation.

The following sections describe the elements and match each element to its programming construct.

Customer


Definition	The shopper who creates the order.
Associated programming construct	`Customer`, which is defined by the `CustomerInput` you provide when you call `createOrder`.
Notes	N/A

Delivery offer


Definition	How the products purchased on the order are agreed to be delivered.
Associated programming construct	`DeliveryOffer`, which is defined by the `DeliveryOfferInput` you provide for a `LineItemInput` when you call `createOrder`.
Notes	If you expect Amazon to fulfill the products associated with a delivery offer, you must provide a `DeliveryOfferDetailsInput` that explicitly sets the `DeliveryProviderInput` to `AMAZON`. Amazon fulfillment can be done through Prime or independent of Prime. For Prime fulfillment, you must pass the corresponding identifiers from a `DeliveryOffer` generated for the products. You must also provide a `DeliveryTermsInput` with `isPrimeEligible` set to `true`. If you instead want the products to be fulfilled by Amazon but not through Prime, set `isPrimeEligible` to `false` and specify the appropriate `deliverySpeed`.If you don't expect Amazon to fulfill the delivery offer, you must set the `DeliveryProviderInput` to `MERCHANT`. You can still provide as much detail as you like either by using the `DeliveryOfferSummaryInput` or `DeliveryOfferDetailsInput`.

Delivery terms


Description	The terms of the delivery offer to generate.
Associated programming construct	`DeliveryTerms`, which is defined by the `DeliveryTermsInput` that you provide for a `DeliveryOfferInput` when you call the `createOrder` mutation or the `deliveryPreview` query.
Notes	Amazon fulfillment can be done through Prime or independent of Prime. For Prime fulfillment, you must set `isPrimeEligible` to `true` in the `DeliveryTermsInput`. If you instead want the products to be fulfilled by Amazon but not through Prime, set `isPrimeEligible` to `false` and specify the appropriate `deliverySpeed`.

Discount allocations

Description Information about discounts allocated to orders, line items, or delivery offers.

Associated programming construct DiscountAllocations, which is defined by the DiscountAllocationInput you provide for a LineItemInput or CreateOrderInput when you call createOrder.


Description	Information about discounts allocated to orders, line items, or delivery offers.
Associated programming construct	`DiscountAllocations`, which is defined by the `DiscountAllocationInput` you provide for a `LineItemInput` or `CreateOrderInput` when you call `createOrder`.
Notes	You can provide varying amounts of details about an order's discounts by using the `DiscountAllocationDetailsInput` and `DiscountAllocationsSummaryInput` constructs. Providing details about discounts and taxes enables Buy with Prime to show estimated refunds as shoppers perform actions like cancellations or returning an item that was offered through Buy with Prime.

Notes

You can provide varying amounts of details about an order's discounts by using the DiscountAllocationDetailsInput and DiscountAllocationsSummaryInput constructs.

Providing details about discounts and taxes enables Buy with Prime to show estimated refunds as shoppers perform actions like cancellations or returning an item that was offered through Buy with Prime.

Line item


Description	A single product to fulfill on an order.
Associated programming construct	`LineItem`, which is defined by the `LineItemInput` you provide when you call `createOrder`.
Notes	N/A

Order

Description An instance of a Buy with Prime order.

Associated programming construct Order, which is defined by the CreateOrderInput you provide when you call createOrder.


Description	An instance of a Buy with Prime order.
Associated programming construct	`Order`, which is defined by the `CreateOrderInput` you provide when you call `createOrder`.
Notes	We recommend that you provide as many details about orders as possible to reduce any ambiguities the shopper might have when looking at the state of an order. The query input takes either an `orderIdentifier` or an `orderId`, never both. `CreateOrderInput` contains a field, `desiredExecutionState`, which you can set to `STARTED` to indicate that you want the order to be fulfilled immediately. If you want to create the order but not start fulfillment until you call the `updateOrder` mutation, set `desiredExecutionState` to `NOT_STARTED`. The default value of `desiredExecutionState` is `NOT_STARTED`. The following figure shows how `desiredExecutionState` affects order fulfillment.

Notes

We recommend that you provide as many details about orders as possible to reduce any ambiguities the shopper might have when looking at the state of an order.

The query input takes either an orderIdentifier or an orderId, never both.

CreateOrderInput contains a field, desiredExecutionState, which you can set to STARTED to indicate that you want the order to be fulfilled immediately. If you want to create the order but not start fulfillment until you call the updateOrder mutation, set desiredExecutionState to NOT_STARTED. The default value of desiredExecutionState is NOT_STARTED. The following figure shows how desiredExecutionState affects order fulfillment.

How desiredExecutionState affects order fulfillment — How `desiredExecutionState` Affects Order Fulfillment

Order cancellation


Description	An action that a shopper, merchant, or merchant-authorized person can take to request cancellation of all Buy with Prime items in a previously placed order. For the steps to cancel orders, see Steps to Cancel Orders. Note: Requesting order cancellation doesn't guarantee cancellation of the order. The Buy with Prime API supports order cancellation for the following order types: single SKU orders, multi-SKU orders, and orders that are a mix of products that are eligible for Buy with Prime, and not eligible for Buy with Prime. You currently can't use the Buy with Prime API to request cancellation for a subset of items in the order, a partial quantity of items in the order, or items that aren't eligible for Buy with Prime.
Associated programming construct	You use the `cancelOrder` mutation to request an order cancellation. You can find order cancellation details by using the `order` query.
Notes	The cancellation state for a `lineItem` can be `PENDING`, `REJECTED`, or `SUCCESS`. The cancellation reason for a line item can be `ORDERED_BY_MISTAKE`, `ITEMS_ARRIVING_LATE`, `INCORRECT_SHIPPING_ADDRESS`, `OUT_OF_STOCK`, `PAYMENT_ISSUE`, or `OTHER`. For definitions of the states and reasons, see `CancellationDetails`. The ability to successfully cancel an order depends on the order's fulfillment status, which you can find in the `state` field of the `PackageInformationDetails`: If ALL line items are in the `PENDING` state, you can submit a Buy with Prime cancellation request. However, submitting a request doesn't guarantee cancellation. After ANY line item isn't in the `PENDING` state, Buy with Prime cancellation requests are no longer allowed. If you make a cancellation request for a shipped order, you will get an error.

Description

An action that a shopper, merchant, or merchant-authorized person can take to request cancellation of all Buy with Prime items in a previously placed order. For the steps to cancel orders, see Steps to Cancel Orders.

Note: Requesting order cancellation doesn't guarantee cancellation of the order.

The Buy with Prime API supports order cancellation for the following order types: single SKU orders, multi-SKU orders, and orders that are a mix of products that are eligible for Buy with Prime, and not eligible for Buy with Prime.

You currently can't use the Buy with Prime API to request cancellation for a subset of items in the order, a partial quantity of items in the order, or items that aren't eligible for Buy with Prime.

Associated programming construct You use the cancelOrder mutation to request an order cancellation. You can find order cancellation details by using the order query.

Notes

The cancellation state for a lineItem can be PENDING, REJECTED, or SUCCESS. The cancellation reason for a line item can be ORDERED_BY_MISTAKE, ITEMS_ARRIVING_LATE, INCORRECT_SHIPPING_ADDRESS, OUT_OF_STOCK, PAYMENT_ISSUE, or OTHER. For definitions of the states and reasons, see CancellationDetails.

The ability to successfully cancel an order depends on the order's fulfillment status, which you can find in the state field of the PackageInformationDetails:

If ALL line items are in the PENDING state, you can submit a Buy with Prime cancellation request. However, submitting a request doesn't guarantee cancellation.
After ANY line item isn't in the PENDING state, Buy with Prime cancellation requests are no longer allowed. If you make a cancellation request for a shipped order, you will get an error.

Order links


Description	Links surfaced as call to actions to manage the order on your site.
Associated programming construct	`OrderLink`, which is defined by the `OrderLinkInput` you provide when you call `createOrder`.
Notes	Order links can be especially useful if the order contains a mix of products, some of which are fulfilled by Amazon and some of which aren't fulfilled by Amazon.

Package information


Description	Details about packages associated with the delivery of products in the order. This information includes the state of the package, estimated delivery date, and so on. You can use this information to sync the package information for Buy with Prime products to other systems.
Associated programming construct	`PackageInformation`, which is initially based on the `DeliveryOfferInput` that you provide for a `LineItemInput` when you call `createOrder`.
Notes	Currently, you can’t use this construct to represent package information for products that aren’t fulfilled by Amazon.

Payments

Description Details about the payment transactions on the order.

Associated programming construct Payments, which is defined by the PaymentsInput you provide when you call createOrder.


Description	Details about the payment transactions on the order.
Associated programming construct	`Payments`, which is defined by the `PaymentsInput` you provide when you call `createOrder`.
Notes	Buy with Prime doesn't manage payments, but you are currently expected to provide minimal details to preserve the shopper experience. You can provide varying amounts of information by using `PaymentSummary` or `PaymentDetails`. `PaymentSummary` defines the minimum information required to represent payments, such as amount paid, method of payment, and the state. `PaymentDetails`, on the other hand, can contain a breakdown of payment transactions that happened on the order. Providing details about payment transactions is optional and is usually recommended to avoid confusion for both Buy with Prime Assist or other support channels to guide any queries about the order for both shopper or merchants.

Notes

Buy with Prime doesn't manage payments, but you are currently expected to provide minimal details to preserve the shopper experience.

You can provide varying amounts of information by using PaymentSummary or PaymentDetails. PaymentSummary defines the minimum information required to represent payments, such as amount paid, method of payment, and the state. PaymentDetails, on the other hand, can contain a breakdown of payment transactions that happened on the order.

Providing details about payment transactions is optional and is usually recommended to avoid confusion for both Buy with Prime Assist or other support channels to guide any queries about the order for both shopper or merchants.

Product

Description The product being purchased as part of the order.

Associated programming construct PurchasedProductView, which is defined by the LineItemInput you provide when you call createOrder.


Description	The product being purchased as part of the order.
Associated programming construct	`PurchasedProductView`, which is defined by the `LineItemInput` you provide when you call `createOrder`.
Notes	The merchant owns the merchandising information for purchased products. The information that you provide depends on whether the item is fulfilled by Amazon. For Buy with Prime items, merchants typically provide the title, price, identifier, and variant information (if applicable). Titles are shown to shoppers when Buy with Prime orders are displayed on Amazon.com and in the order detail page and order notifications. For non-Buy with Prime items that are part of the overall order, details about the purchased item are optional.

Notes

The merchant owns the merchandising information for purchased products.

The information that you provide depends on whether the item is fulfilled by Amazon. For Buy with Prime items, merchants typically provide the title, price, identifier, and variant information (if applicable). Titles are shown to shoppers when Buy with Prime orders are displayed on Amazon.com and in the order detail page and order notifications.

For non-Buy with Prime items that are part of the overall order, details about the purchased item are optional.

Recipient


Description	The person who receives the order. The recipient might be the customer or someone the customer chose to receive the order.
Associated programming construct	`Recipient`, which is defined by the `RecipientInput` you provide when you call `createOrder`.
Notes	N/A

Refunds

Description Information about Buy with Prime items that the shopper is refunded.

Associated programming construct Refunds, which is within the Order construct.


Description	Information about Buy with Prime items that the shopper is refunded.
Associated programming construct	`Refunds`, which is within the `Order` construct.
Notes	You can provide varying amounts of information by using `RefundSummary` or `RefundDetails`. `PaymentSummary` defines the minimum information required to represent payments, such as amount paid, method of payment, and the state. `PaymentDetails`, on the other hand, can contain a breakdown of payment transactions that happened on the order. If Buy with Prime provides notifies you that a refund is due as part of an order cancellation or return, we expect you to provide `RefundDetails` to show as much information as possible to the shopper about the corresponding refund that you issue. For refunds that you issue unrelated to Buy with Prime items, it's acceptable to provide just a `RefundSummary`.

Notes

You can provide varying amounts of information by using RefundSummary or RefundDetails. PaymentSummary defines the minimum information required to represent payments, such as amount paid, method of payment, and the state. PaymentDetails, on the other hand, can contain a breakdown of payment transactions that happened on the order.

If Buy with Prime provides notifies you that a refund is due as part of an order cancellation or return, we expect you to provide RefundDetails to show as much information as possible to the shopper about the corresponding refund that you issue. For refunds that you issue unrelated to Buy with Prime items, it's acceptable to provide just a RefundSummary.

Returns

Description Information about Buy with Prime items that the shopper returns.

Associated programming construct Returns, which is within the Order construct.


Description	Information about Buy with Prime items that the shopper returns.
Associated programming construct	`Returns`, which is within the `Order` construct.
Notes	Buy with Prime allows shoppers to return a Buy with Prime item in a self-service manner by using Amazon-hosted experiences. In any case, any returns that were initiated or processed are represented by the `Returns` construct on the order. Currently, you can’t use this construct to represent returns for products that aren't offered through Buy with Prime.

Notes

Buy with Prime allows shoppers to return a Buy with Prime item in a self-service manner by using Amazon-hosted experiences. In any case, any returns that were initiated or processed are represented by the Returns construct on the order.

Currently, you can’t use this construct to represent returns for products that aren't offered through Buy with Prime.

Taxes


Description	Minimal information about at various granularities as applicable.
Associated programming construct	`Taxes`, which is defined by the `TaxInput` you specify for an order or line item when you call `createOrder`.
Notes	Currently, Buy with Prime doesn't customize any tax calculations on the order, so we expect that you provide only minimal information about tax (that is, the tax amount at the applicable granularities). The Buy with Prime API supports the ingestion of tax information at the order, line item, and delivery levels.

Total price


Description	The total price the shopper paid for the order on your site.
Associated programming construct	`OrderTotalSummaryInput`, which you provide when you call `createOrder`.
Notes	This value can help reduce ambiguity about the total price of the order given that the shopper can view and manage their Buy with Prime order on your website as well as on Amazon.com.

API operations

The Buy with Prime Order interface supports the following mutations, queries, and events.

Mutations

Name	Description
`createOrder`	Creates a Buy with Prime order.
`updateOrder`	Updates an existing Buy with Prime order.
`cancelOrder`	Requests cancellation of a Buy with Prime order.

Queries

Name	Description
`order`	Gets a Buy with Prime order.

Events

Event	When Event is Published
`PACKAGE_DELIVERY_CANCELLED`	One or more items were successfully cancelled from the specified order prior to delivery.
`PACKAGE_DELIVERED`	One or more items were delivered to their destination.
`PACKAGE_DELIVERY_IN_TRANSIT`	One or more items in the specified order were fulfilled by Amazon logistics.
`PACKAGE_TRACKER_MILESTONE_CHANGED`	A milestone of a Buy with Prime tracking number was updated. A milestone represents an event that occurs during the delivery process for the associated tracking number.
`REFUND_REQUESTED`	There is a request to issue a refund for one or more items.
`RETURN_COMPLETED`	A return that was initiated earlier was successfully completed.
`RETURN_STARTED`	A return of one or more purchased items was successfully initiated.

Where to start

To experiment creating an order, call the createOrder mutation. For examples of requests and responses, see Order Interface Examples.

Create and Manage Orders

📘
Important

Terminology

API operations

Mutations

Queries

Events

Where to start

Related topics

📘Important

Terminology

API operations

Mutations

Queries

Events

Where to start

Related topics

📘
Important