Create a Buy with Prime Order

πŸ“˜

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.

This topic provides examples of how to create a Buy with Prime order.

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

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.

To help the shopper understand the state of an order, we recommend that you provide as many details about orders as possible.

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

Note that the response to the createOrder mutation contains links that you can use to direct customers where to manage their Buy with Prime order.

To learn how to call the Buy with Prime API, see Call the Buy with Prime API.

Sample data

The examples in this topic use the following sample data.

Sample product details
{ title: "In Search of Lost Time", isbn: "example-isbn-1", isPrimeIntended: true, sku: "example-sku-1", mSku: "example-msku-1", imageUrl: "https://example.com/images/example-image-1.jpg", detailPageUrl: "https://www.amazon.com/dp/example-detail-page-1", price: { amount: "10.00", currencyCode: "USD" } variationDetails: [ { type: "format", value: "Hardcover" }, { type: "version", value: "Abridged" } ] }
{ title: "Pride and Prejudice", isbn: "example-isbn-2", isPrimeIntended: true, sku: "example-sku-2", mSku: "example-msku-2", imageUrl: "https://example.com/images/example-image-2.jpg", detailPageUrl: "https://www.amazon.com/dp/example-detail-page-2", variationDetails: [ { format: "Paperback" } ] }
Sample customer details
{ contact: { name: "Jane Doe", email: "jane_doe@example.com" } }
Sample recipient details

Typically, an individual creates an order for themselves. Less common scenarios, such as gifting, require the representation of recipients independently from the customer placing the order. To provide this flexibility, Buy with Prime doesn't assume that the customer who creates the order is the same as the person who receives it.

{ deliveryAddress: { name: "John Doe", streetAddress: "440 Terry Ave N" , locality: "Seattle", region: "WA", countryCode: "US", postalCode: "98109", contactNumber: "206-555-0100" } }
Sample delivery offer details

Prior to placing the order, you Create Delivery Previews to provide one or more delivery offers to the customer. The customer selects a delivery offer, and you include the associated delivery preview ID and delivery offer ID from the selectedDeliveryOffer object to the createOrder mutation.

When you generate a delivery preview that you can use to create an order, it is crucial to use accurate delivery preview terms. For details, see Create Delivery Previews.

# See other tab for sampleDeliveryPreviewQueryResponse # Assume that the first delivery offer from the delivery group is selected to create a fulfillment order deliveryPreviewId: sampleDeliveryPreviewQueryResponse["data"]["deliveryPreview"]["id"] deliveryOfferId: sampleDeliveryPreviewQueryResponse["data"]["deliveryGroups"][0]["deliveryOffers"][0]["id"]
{ "data": { "deliveryPreview": { "id": "example-delivery-preview-id", "deliveryGroups": [ { "id": "example-delivery-group", "items": [ { "itemIdentifier": { "__typename": "SKU", "value": "example-sku-1" # In Search of Lost Time SKU }, "quantity": { "unit": "UNIT", "amount": 1 } } ], "deliveryOffers": [ { "id": "example-delivery-offer-id-1", "charge": { "totalCharge": { "currencyCode": "USD", "amount": 0 }, "rollupCharges": [ ] }, "date": { "earliest": "2023-08-24T03:00:00Z", "latest": "2023-08-28T03:00:00Z" }, "policy": { "messaging": { "messageText": "Get it on August 24", "locale": "en-US", "badge": "PRIME" } }, "expiresAt": "2023-08-21T21:27:35.016842Z" }, { "id": "example-delivery-offer-id-2", "charge": { "totalCharge": { "currencyCode": "USD", "amount": 0 }, "rollupCharges": [ ] }, "date": { "earliest": "2023-08-26T14:14:06Z", "latest": "2023-08-30T14:14:06Z" }, "policy": { "messaging": { "messageText": "Get it on August 26th", "locale": "en-US", "badge": "PRIME" } }, "expiresAt": null } ] } ] } } }

Create a minimum fulfillable Buy with Prime order

This example shows how to use the createOrder mutation to create a simple Buy with Prime order. In this example, Jane Doe (the Customer) orders a book (the PurchasedItem) to be delivered to John Doe (the Recipient).

Note that desiredExecutionState is set to STARTED, which means that fulfillment will start immediately. If you want to create the order but not start fulfillment right away, set desiredExecutionState to NOT_STARTED. If you set desiredExecutionState to NOT_STARTED, fulfillment of the order will not start until you call updateOrder, which sets the state to STARTED.

Request
// Variables from sample data inSearchOfLostTimeBook deliveryPreviewId deliveryOfferId reversalOfferId janeDoeCustomer johnDoeRecipient mutation createOrder($input: CreateOrderInput) { createOrder(input: $input) { id orderLinks { destinationType url } } } // Mutation variables { "input": { "desiredExecutionState": "STARTED", "customer": janeDoeCustomer, "recipient":johnDoeRecipient, "lineItems": [ { "purchasedItem": { "itemId": { "space": "SKU", "value": inSearchOfLostTimeBook.sku }, "title": inSearchOfLostTimeBook.title, "price": { "currentPrice": { "amount": inSearchOfLostTimeBook.price.amount, "currencyCode": inSearchOfLostTimeBook.price.currencyCode } } }, "quantity": { "amount": 1 }, "selectedDeliveryOffer": { "details": { "deliveryPreviewId": deliveryPreviewId, "id": deliveryOfferId, "deliveryProvider": "BUY_WITH_PRIME" } } } ], "orderTotal": { "totalPrice": { "amount": 10, "currencyCode": "USD" } }, "shopperIdentity": { "apayCheckoutSessionId": { "value": "testToken", "externalId: "externalId1" } } } }
Response
orderResponse = { "data": { "createOrder": { "id": "example-order-id", "orderLinks": [ { "destinationType": "BWP_STOREFRONT", "url": "https://order.buywithprime.amazon.com/orders/example" } ] } } }

Create a single-item order with external order details

When you create a Buy with Prime order, Buy with Prime associates the order with a unique ID. You can also associate the order with external information such as aliases (external order identifiers that you can use to query the order later), order links (URLs for managing the order in external order management systems), and a total order price that was computed outside of Buy with Prime.

The following example shows how to supply order aliases, order links, and an order total when you create an order.

Request
// GraphQL mutation mutation createOrder($input: CreateOrderInput) { createOrder(input: $input) { id orderLinks { destinationType url } } } // Mutation variables { "input": { // Alias for the order from an alternate order management system "orderAliases": [ { "aliasType": "EXTERNAL_ID", "aliasId": "example-alias-id" } ], "orderLinks": [ { "destinationType": "EXTERNAL_STOREFRONT", "url": "https://example.com/orders/1234" } ], "orderTotal": { "totalPrice": { "amount": 10, "currencyCode": "USD" } }, "shopperIdentity": { "apayCheckoutSessionId": { "value": "testToken", "externalId: "externalId1" } } ... "lineItems": [ { ... // Alias for the line item on the order from the alternate order manager. // Useful only if this is a multi-line item order. "lineItemAliases" [ { "aliasType": "EXTERNAL_ID", "aliasId": "example-line-item-alias-id" } ], "selectedDeliveryOffer": { "details": { ... // Line item associations linking this delivery offer with the // line item alias provided above. "lineItemAssociations": [ { "lineItemId": { "lineItemAlias": { "aliasType": "EXTERNAL_ID", "aliasId": "example-line-item-alias-id" } } } ] } } } ], ... } }
Response
orderResponse = { "data": { "createOrder": { "id": "example-order-id", "orderLinks": [ { "destinationType": "BWP_STOREFRONT", "url": "https://order.buywithprime.amazon.com/12345/orders/example-order-id" }, { "destinationType": "EXTERNAL_STOREFRONT", "url": "https://example.com/orders/1234" } ] } } }

Create an order that includes an item that isn't eligible for Buy with Prime

You can create orders that include items that aren't eligible for Buy with Prime. The following example shows how to create an order that contains an item that's eligible for Buy with Prime (In Search of Lost Time) and an item that's not eligible for Buy with Prime (Pride and Prejudice).

Request
// Variables from sample data inSearchOfLostTimeBook # Eligible for Buy with Prime prideAndPrejudiceBook # Not eligible for Buy with Prime selectedDeliveryPreview janeDoeCustomer johnDoeRecipient // GraphQL mutation mutation createOrder($input: CreateOrderInput) { createOrder(input: $input) { id orderLinks { destinationType url } } } // Mutation variables { "input":{ "desiredExecutionState":"STARTED", "customer": janeDoeCustomer, "recipient":johnDoeRecipient, "lineItems":[ // Line item representing In Search of Lost Time { "purchasedItem":{ "itemId":{ "space":"SKU", "value":inSearchOfLostTimeBook.sku }, "title":inSearchOfLostTimeBook.title, "price":{ "currentPrice":{ "amount":inSearchOfLostTimeBook.price.amount, "currencyCode":inSearchOfLostTimeBook.price.currencyCode } }, "variantSelections":[ { "variantType":inSearchOfLostTimeBook.variationDetails.[0].type, "variantValue":inSearchOfLostTimeBook.variationDetails.[0].value }, { "variantType":inSearchOfLostTimeBook.variationDetails.[1].type, "variantValue":inSearchOfLostTimeBook.variationDetails.[1].value } ] }, "quantity":{ "amount":1 }, "selectedDeliveryOffer":{ "details":{ "deliveryPreviewId":selectedDeliveryPreview.deliveryPreviewId, "id":selectedDeliveryPreview.deliveryOfferId, "deliveryProvider":"BUY_WITH_PRIME" } }, "taxes":{ "summary":{ "collectableTaxAmount":{ "amount":"1.00", "currencyCode":"USD" } } } }, // Line item representing Pride and Prejudice { "purchasedItem":{ "title":prideAndPrejudiceBook.title }, "quantity":{ "amount":1 }, "selectedDeliveryOffer":{ "summary":{ // Indicator to Buy with Prime that this item delivery is managed by the merchant "deliveryProvider":"MERCHANT", "deliveryCharge":{ "amount":"3.00", "currencyCode":"USD" }, "deliveryMessage":{ "messageText":"Standard Delivery! Ships in 3-5 business days" } } } } ], "discounts":{ "summary":{ "amount":"5.00", "displayString":"FIRSTORDER (coupon code)" } }, ], "orderTotal": { "totalPrice": { "amount": 10, "currencyCode": "USD" } }, "shopperIdentity": { "apayCheckoutSessionId": { "value": "testToken", "externalId: "externalId1" } }, "payments": { "summary": { "amount": { "amount": "10.20", "currecyCode": "USD" }, "paymentMethodDisplayString": "CREDIT_CARD", "state": "CAPTURED" } } } }
Response
orderResponse = { "data": { "createOrder": { "id": "example-order-id", "orderLinks": [ { "destinationType": "BWP_STOREFRONT", "url": "https://order.buywithprime.amazon.com/12345/orders/example-order-id" }, { "destinationType": "EXTERNAL_STOREFRONT", "url": "https://example.com/orders/1234" } ] } } }

Related topics


Did this page help you?