Create and Manage Orders

📘

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.

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:

Terminology

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

Note that you can associate many attributes at both the line item and order 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.

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

Customer
DefinitionThe shopper who creates the order.
Associated programming constructCustomer, which is defined by the CustomerInput you provide when you call createOrder.
NotesN/A
Delivery information
DefinitionDetails about delivery of items in the order. This information includes the state of delivery, estimated delivery date, and so on. You can use this information to sync the delivery information for the Buy with Prime items to other systems.
Associated programming constructDeliveryInformation, which is initially based on the DeliveryOfferInput you provide for a LineItemInput when you call createOrder.
NotesCurrently, you can’t use this construct to represent delivery information for products that aren’t offered through Buy with Prime.
Delivery offer
DefinitionHow the products purchased on the order are agreed to be delivered.
Associated programming constructDeliveryOffer, 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 DeliveryOfferProviderInput to BUY_WITH_PRIME. You must also pass the corresponding identifiers from a DeliveryOffer generated for the products.

If you don’t expect Amazon to fulfill the delivery offer, you must set the DeliveryOfferProviderInput to MERCHANT. You can still provide as much detail as you like either by using the DeliveryOfferSummaryInput or DeliveryOfferDetailsInput.

Discount allocations
DescriptionInformation about discounts allocated to orders, line items, or delivery offers.
Associated programming constructDiscountAllocations, 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.

Line item
DescriptionA single product to fulfill on an order.
Associated programming constructLineItem, which is defined by the LineItemInput you provide when you call createOrder.
NotesN/A
Order
DescriptionAn instance of a Buy with Prime order.
Associated programming constructOrder, 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.

How desiredExecutionState affects order fulfillment

How desiredExecutionState Affects Order Fulfillment

Order links
DescriptionLinks surfaced as call to actions to manage the order on your site.
Associated programming constructOrderLink, which is defined by the OrderLinkInput you provide when you call createOrder.
NotesOrder 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.
Order total
DescriptionThe total price the shopper paid for the order on your site.
Associated programming constructOrderTotalSummary, which is defined by the OrderTotalSummaryInput you provide when you call createOrder.
NotesThis 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.
Payments
DescriptionDetails about the payment transactions on the order.
Associated programming constructPayments, 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.

Purchased item
DescriptionThe product being purchased as part of the order.
Associated programming constructPurchasedItem, 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.

Recipient
DescriptionThe person who receives the order. The recipient might be the customer or someone the customer chose to receive the order.
Associated programming constructRecipient, which is defined by the RecipientInput you provide when you call createOrder.
NotesN/A
Refunds
DescriptionInformation about Buy with Prime items that the shopper is refunded.
Associated programming constructRefunds, 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.

Returns
DescriptionInformation about Buy with Prime items that the shopper returns.
Associated programming constructReturns, 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.

Taxes
DescriptionMinimal information about at various granularities as applicable.
Associated programming constructTaxes, which is defined by the TaxInput you specify for an order or line item when you call createOrder.
NotesCurrently, 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.

API operations

You use the following mutations, queries, and events to create and manage orders.

Mutations

NameDescription
createOrderCreates a Buy with Prime order.
updateOrderUpdates an existing Buy with Prime order.

Queries

NameDescription
orderGets a Buy with Prime order.

Events

EventWhen Event is Published
ITEM_CANCELLEDOne or more items were successfully cancelled from the specified order prior to delivery.
ITEM_DELIVEREDOne or more items were delivered to their destination.
ITEM_IN_TRANSITOne or more items in the specified order were fulfilled by Amazon logistics.
REFUND_REQUESTEDThere is a request to issue a refund for one or more items.
RETURN_COMPLETEDA return that was initiated earlier was successfully completed.
RETURN_STARTEDA return of one or more purchased items was successfully initiated.

Where to start

To experiment creating an order, call the createOrder mutation. For details, see Create a Buy with Prime Order.

Related topics