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
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 information
Definition | Details 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 construct | DeliveryInformation , which is initially based on the DeliveryOfferInput you provide for a LineItemInput when you call createOrder . |
Notes | Currently, you can’t use this construct to represent delivery information for products that aren’t offered through Buy with Prime. |
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 If you don’t expect Amazon to fulfill the delivery offer, you must set the |
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 . |
Notes | You can provide varying amounts of details about an order's discounts by using the 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 . |
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
|
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. |
Order total
Description | The total price the shopper paid for the order on your site. |
Associated programming construct | OrderTotalSummary , which is defined by the OrderTotalSummaryInput 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. |
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 . |
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 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
Description | The product being purchased as part of the order. |
Associated programming construct | PurchasedItem , 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
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. |
Notes | You can provide varying amounts of information by using 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 |
Returns
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 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. |
API operations
You use the following mutations, queries, and events to create and manage orders.
Mutations
Name | Description |
---|---|
createOrder | Creates a Buy with Prime order. |
updateOrder | Updates an existing Buy with Prime order. |
Queries
Name | Description |
---|---|
order | Gets a Buy with Prime order. |
Events
Event | When Event is Published |
---|---|
ITEM_CANCELLED | One or more items were successfully cancelled from the specified order prior to delivery. |
ITEM_DELIVERED | One or more items were delivered to their destination. |
ITEM_IN_TRANSIT | One or more items in the specified order were fulfilled by Amazon logistics. |
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 details, see Create a Buy with Prime Order.
Related topics
Updated 3 days ago