Buy with Prime | Developer Documentation
Documentation
GraphQL Playground

Best Practices for 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.

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, consider the following requirements when using 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 PurchasedItemInput of the createOrder mutation must match the item identifiers of the selected delivery item from the response to a deliveryPreview query. If you use a SKU as the identifier, it must be unique in your catalog.
  • The item quantity in QuantityInput 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

You can use an order alias to associate a Buy with Prime order with a unique identifier in your system. Consider 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.
  • The maximum number of aliases per order is five. If the input has more than five order aliases, the API call fails with a ValidationException.

Updating the execution state

Use OrderExecutionStateInput as an optional input to configure when to start fulfillment of Buy with Prime items based on your ordering flows. If you don't provide a value, the Buy with Prime API sets this state to NOT_STARTED to indicate 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 deliveryInformation 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 display these errors to shoppers to let them decide if they want to reduce the requested item quantity before placing the order.

Related topics

Updated 6 months ago