📘

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

This topic provides best practices for when you Create and Manage Orders.

Providing order details

We recommend that you provide as many details to createOrder as possible. In particular, we strongly recommend that you specify any monetary charges on the order, such as discounts or taxes, at the line-item level.

Providing payment details

Although you only need to provide minimal payment information, we recommend that you provide payment transaction details to help provide guidance for any shopper queries about the order.

Specifying a delivery preview

To avoid API call failures related to delivery previews, make sure that you heed the following requirements when you use createOrder or updateOrder to include line items for a Buy with Prime order. For details about troubleshooting orders, see Troubleshoot Order Errors.

• The identifiers that you provide to the ProductIdentifierInput of the createOrder mutation must match the item identifiers of the selected delivery item from the response to a deliveryPreview query.
• The value in AmountInput must match the quantity of the delivery item in the selected delivery offer from the deliveryPreview response.
• The deliveryPreviewId in the DeliveryOfferDetailsInput must match the deliveryPreviewId from the deliveryPreview response.
• The selectedDeliveryOffer.details.id in the DeliveryOfferDetailsInput must match the selected deliveryOffer.id from the deliveryPreview response.
• If you pass a shipping address as an input to the deliveryPreview query, ensure that the deliveryAddress in the RecipientInput of the call to createOrder or updateOrder matches the shopper's provided shipping address that you used to generate the delivery preview.
• The shopperIdentityinformation that you capture through the IdentityTokenInput must match the shopperIdentity information from the deliveryPreview response. If you pass in a valid idpToken that belongs to a different shopper , the API call fails with an ValidationException with code ShopperIdMismatch.

Using order aliases

Order aliases enable you to associate Buy with Prime orders with unique identifiers in your systems. When you use order aliases, heed the following requirements:

• The Buy with Prime API requires order aliases to be unique across orders in the same store. If you use a non-unique order alias while you create or update an order, the API call fails with a ValidationException.
• Currently, the Buy with Prime API allows a maximum of five order aliases per order. If the input has more than five order aliases, the API call fails with a ValidationException.

Updating the execution state

The OrderExecutionStateInput enables you to configure when to trigger fulfillment of Buy with Prime items based on your ordering flows. The OrderExecutionStateInput is an optional input. If you don't provide a value, the Buy with Prime API sets this state to NOT_STARTED, which indicates that the order is confirmed but fulfillment hasn't started. When the order is in this state, you can call the updateOrder mutation to set the desiredExecutionState to STARTED to start fulfillment.

However, the API call fails when the requested action can't be taken based on the value you provide to the API, such as in the following examples:

• If the executionState is STARTED and you call updateOrder to set the state to NOT_STARTED, the API call fails with error code InvalidOrderExecutionState. To avoid this error, query the order to check the executionState before you update the order.
• If the executionState is STARTED and the packageInformation indicates that the delivery of the order is IN_TRANSIT or CANCELLED, if you call updateOrder to set the state to STARTED, the API call fails with error code ExecutionAlreadyStarted or ExecutionCannotBeStartedDueToCancellation, respectively. To minimize this error, investigate the order execution flow in your system and avoid updating the executionState in such cases.

Avoiding inventory failures

When you use the createOrder mutation to place a Buy with Prime order, sometimes the requested item quantities aren't available in Buy with Prime inventory even though the deliveryOffer for that item is still valid. This situation especially occurs when multiple shoppers try to purchase the same items and Buy with Prime inventory doesn't have sufficient quantities to fulfill all requests.

In these cases, the createOrder mutation fails with a ValidationException with code SelectedQuantityNotAvailable. If the item is out of stock, the error code is ItemOutOfStock. The best course of action in the case of these errors depends on whether you placed the order in your system yet. If you haven't placed the order in your system, it's best to surface these errors to shoppers to enable them to decide if they want to reduce the requested item quantity before placing the order.

Use sandbox shopper identity tokens during testing

In the sandbox environment, to call deliveryPreview, shopperBwPEligibility, or createOrder, you must use one of the Sandbox shopper identity tokens.

Related topics

• Create and Manage Orders
• Create a Buy with Prime Order
• Update a Buy with Prime Order
• Query a Buy with Prime Order
• Cancel a Buy with Prime Order