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.
The response to the createOrder mutation contains the complete order and links that you can use to direct customers where to manage their Buy with Prime order.
Currently, you can create orders with a maximum of 40 items: 20 items that are eligible for Buy with Prime, and 20 items that aren't eligible for Buy with Prime.
To learn how to call the Buy with Prime API, see Call the Buy with Prime API.
In the sandbox environment, to call deliveryPreview, shopperBwPEligibility, or createOrder, you must use one of the Sandbox shopper identity tokens.
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",
buyWithPrimeProductId: "example-product-id-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: "[email protected]"
}
}
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 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",
"products": {
"productIdentifier": {
"value": String
},
"amount": {
"unit": String,
"value": Bigdecimal
}
},
"deliveryOffers": [
{
"id": "example-delivery-offer-id-1",
"price": {
"totalPrice": {
"currencyCode": "USD",
"amount": 0
},
"rollupPrices": [
]
},
"deliveryTerms": {
"isPrimeEligible": "true"
},
"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",
"price": {
"totalPrice": {
"currencyCode": "USD",
"amount": 0
},
"rollupPrices": [
]
},
"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 Product) 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
productId
inSearchOfLostTimeBookVariationDimension
inSearchOfLostTimeBookVariationDimensionValue
deliveryPreviewId
deliveryOfferId
reversalOfferId
janeDoeCustomer
johnDoeRecipient
mutation createOrder($input: CreateOrderInput) {
createOrder(input: $input) {
order {
id
}
}
}
// Mutation variables
{
"input": {
"desiredExecutionState": "STARTED",
"customer": janeDoeCustomer,
"recipient":johnDoeRecipient,
"lineItems": [
{
"product": {
"identifier": {
"productId": inSearchOfLostTimeBook.buyWithPrimeProductId,
},
"title": inSearchOfLostTimeBook.title,
"price": {
"amount": inSearchOfLostTimeBook.price.amount,
"currencyCode": inSearchOfLostTimeBook.price.currencyCode
}
},
"amount": {
"unit": "UNIT",
"value": 1
},
"selectedDeliveryOffer": {
"details": {
"deliveryPreviewId": deliveryPreviewId,
"id": deliveryOfferId,
"deliveryProvider": "AMAZON",
"deliveryTerms": {
"isPrimeEligible": true
}
}
}
}
],
"orderTotal": {
"totalPrice": {
"amount": 10,
"currencyCode": "USD"
}
},
"shopperIdentity": {
"apayCheckoutSessionId": {
"value": "testToken",
"externalId: "externalId1"
}
}
}
}
Response
orderResponse =
{
"data": {
"order": {
"id": "example-order-id"
}
}
}
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) {
order {
id
}
}
}
// Mutation variables
{
"input": {
// Alias for the order from an alternate order management system
"aliases": [
{
"aliasType": "EXTERNAL_ID",
"aliasId": "example-alias-id"
}
],
"orderLinks": [
{
"destinationType": "EXTERNAL_STOREFRONT",
"url": "https://example.com/orders/1234"
}
],
"totalPrice": {
"amount": 10.20,
"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.
"aliases" [
{
"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": {
"alias": {
"aliasType": "EXTERNAL_ID",
"aliasId": "example-line-item-alias-id"
}
}
}
]
}
}
}
],
...
}
}
Response
orderResponse =
{
"data": {
"order": {
"id": "example-order-id"
}
}
}
Create an order that includes an item that isn't offered through Buy with Prime
You can use the Order API to create orders that include line items that aren't offered through Buy with Prime. The following example shows how to create an order that contains an item that's offered through Buy with Prime (In Search of Lost Time) and an item that's not offered through Buy with Prime (Pride and Prejudice).
Request
// Variables from sample data
inSearchOfLostTimeBook # Offered through Buy with Prime
prideAndPrejudiceBook # Not offered through Buy with Prime
selectedDeliveryPreview
janeDoeCustomer
johnDoeRecipient
// GraphQL mutation
mutation createOrder($input: CreateOrderInput) {
createOrder(input: $input) {
order {
id
}
}
}
// Mutation variables
{
"input": {
"desiredExecutionState":"STARTED",
"customer": janeDoeCustomer,
"recipient":johnDoeRecipient,
"lineItems":[
// Line item representing In Search of Lost Time
{
"product": {
"identifier": {
"productId": inSearchOfLostTimeBook.buyWithPrimeProductId
},
"title":inSearchOfLostTimeBook.title,
"price": {
"amount": inSearchOfLostTimeBook.price.amount,
"currencyCode": inSearchOfLostTimeBook.price.currencyCode
},
"variationSelections": [
{
"dimension": inSearchOfLostTimeBook.variationDetails.[0].dimension,
"value": inSearchOfLostTimeBook.variationDetails.[0].value
}
]
},
"amount": {
"value": 1
},
"selectedDeliveryOffer": {
"details":{
"deliveryPreviewId": selectedDeliveryPreview.deliveryPreviewId,
"id": selectedDeliveryPreview.deliveryOfferId,
"deliveryProvider": "AMAZON",
"deliveryTerms": {
"isPrimeEligible": true
}
}
},
"taxes": {
"summary": {
"collectableTaxAmount": {
"amount": "1.00",
"currencyCode": "USD"
}
}
}
},
// Line item representing Pride and Prejudice
{
"purchasedProduct": {
"productId": productId,
"title": prideAndPrejudiceBook.title,
"price": {
"amount": prideAndPrejudiceBook.price.amount,
"currencyCode": prideAndPrejudiceBook.price.currencyCode
},
"variationSelections": [
{
"dimension": prideAndPrejudiceBook.variationDetails.[0].dimension,
"value": prideAndPrejudiceBook.variationDetails.[0].value
}
]
},
"amount": {
"value": 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)"
}
},
],
"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": {
"order": {
"id": "example-order-id",
}
}
}
Create an order that includes an item to be fulfilled by Amazon but isn't offered through Buy with Prime
You can use the Order API to create orders that include line items that aren't offered through Buy with Prime but still fulfilled by Amazon. The following example shows how to create an order that contains an item that's offered through Buy with Prime (In Search of Lost Time) and an item that's not offered through Buy with Prime but still fulfilled by Amazon (Pride and Prejudice).
Request
// Variables from sample data
inSearchOfLostTimeBook # Offered through Buy with Prime
prideAndPrejudiceBook # Not offered through Buy with Prime
selectedDeliveryPreview
janeDoeCustomer
johnDoeRecipient
// GraphQL mutation
mutation createOrder($input: CreateOrderInput) {
createOrder(input: $input) {
order {
id
}
}
}
// Mutation variables
{
"input": {
"desiredExecutionState":"STARTED",
"customer": janeDoeCustomer,
"recipient":johnDoeRecipient,
"lineItems":[
// Line item representing In Search of Lost Time
{
"product": {
"identifier": {
"productId": inSearchOfLostTimeBook.buyWithPrimeProductId,
},
"title":inSearchOfLostTimeBook.title,
"price": {
"amount": inSearchOfLostTimeBook.price.amount,
"currencyCode": inSearchOfLostTimeBook.price.currencyCode
},
"variationSelections": [
{
"dimension": inSearchOfLostTimeBook.variationDetails.[0].dimension,
"value": inSearchOfLostTimeBook.variationDetails.[0].value
}
]
},
"amount": {
"value": 1
},
"selectedDeliveryOffer": {
"details":{
"deliveryPreviewId": selectedDeliveryPreview.deliveryPreviewId,
"id": selectedDeliveryPreview.deliveryOfferId,
"deliveryProvider": "AMAZON",
"deliveryTerms": {
"isPrimeEligible": true
}
}
},
"taxes": {
"summary": {
"collectableTaxAmount": {
"amount": "1.00",
"currencyCode": "USD"
}
}
}
},
// Line item representing Pride and Prejudice
{
"product": {
"identifier": {
"productId": inSearchOfLostTimeBook.buyWithPrimeProductId,
},
"title": prideAndPrejudiceBook.title,
"price": {
"amount": prideAndPrejudiceBook.price.amount,
"currencyCode": prideAndPrejudiceBook.price.currencyCode
},
"variationSelections": [
{
"dimension": prideAndPrejudiceBook.variationDetails.[0].dimension,
"value": prideAndPrejudiceBook.variationDetails.[0].value
}
]
},
"amount": {
"value": 1
},
"selectedDeliveryOffer": {
"details": {
// Indicator to Buy with Prime that this item is to be delivered by Amazon but via Prime
"deliveryProvider": "AMAZON",
"deliveryTerms": {
"isPrimeEligible": false,
"deliverySpeed": "Standard" // Can also use Expedited
}
"deliveryCharge": {
"amount":"3.00",
"currencyCode":"USD"
}
}
}
}
],
"discounts":{
"summary":{
"amount":"5.00",
"displayString":"FIRSTORDER (coupon code)"
}
},
],
"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": {
"order": {
"id": "example-order-id",
}
}
}
Create an order with items offered through and items not offered through Buy with Prime that belong to a bundled product
The following example shows how to use the createOrder mutation to support bundled product attribution for each line item in the order if the shopper purchases items offered through and items not offered through Buy with Prime as part of the bundled product. When you create the order, in PurchasedProductView specify the optional purchaseGroupMembership field to provide the connection to the bundled product. Within purchaseGroupMembership, use the product field to provide the bundled product view, and use the optional memberAmount field to provide the quantity of the line item attributed to the bundled product.
The following example shows how to create a Buy with Prime order with items that belong to a bundled product, where the bundled product includes items offered through Buy with Prime and items not offered through Buy with Prime.
Request
// GraphQL mutation
mutation createOrder {
createOrder(
input: {
lineItems: [
{
product: {
identifier: {
productId: "example-component-product-1-id"
}
title: "example-component-product-1-title"
price: {
amount: 10.79
currencyCode: "USD"
}
purchaseGroupMembership: {
product: {
identifier: {
sku: "BUNDLE-PRODUCT-TEST"
}
price: {
amount: 20.79
currencyCode: "USD"
}
}
memberAmount: {
value: 1
}
}
}
amount: {
value: 1
}
selectedDeliveryOffer: {
details: {
id: "1234567890"
deliveryPreviewId: "SIP-0000000-000000"
deliveryProvider: AMAZON
deliveryTerms: {
isPrimeEligible: true
}
}
}
},
{
product: {
identifier: {
sku: "example-component-product-2-sku"
}
purchaseGroupMembership: {
product: {
identifier: {
sku: "BUNDLE-PRODUCT-TEST"
}
price: {
amount: 20.79
currencyCode: "USD"
}
}
memberAmount: {
value: 2
}
}
}
amount: {
value: 2
}
selectedDeliveryOffer: {
details: {
deliveryProvider: AMAZON
deliveryTerms: {
isPrimeEligible: false
deliverySpeed: "STANDARD"
}
}
}
}
]
customer: {
contact: {
emailData: {
name: "John Smith"
email: "[email protected]"
}
}
}
recipient: {
deliveryAddress: {
name: "John Smith"
streetAddress: "399 Boren Ave N"
locality: "Seattle"
region: "WA"
countryCode: "US"
postalCode: "98109"
}
}
totalPrice: {
value: {
amount: 20.79
currencyCode: "USD"
}
}
orderLinks: [
{
destinationType: EXTERNAL_ORDER_MANAGEMENT
url: "https://mystore123.com/orders/512968435"
}
]
shopperIdentity: {
apayCheckoutSessionId: {
value: "apay-session-id"
externalId: "external-shopper-checkout-session-id"
}
}
}
) {
order {
id
lineItems {
amount {
unit
value
}
createdAt
product {
title
price {
currencyCode
amount
}
purchaseGroupMembership {
product {
sku
price {
currencyCode
amount
}
}
memberAmount {
value
}
}
}
}
orderLinks {
destinationType
url
}
}
}
}
Response
{
"data": {
"createOrder": {
"order": {
"id": "322-ABC1-AAAAAA",
"lineItems": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"createdAt": "2022-02-22T16:13:11.798Z",
"product": {
"title": "example-component-product-1-title",
"price": {
"currencyCode": "USD",
"amount": 10.79
},
"purchaseGroupMembership": {
"product": {
"sku": "BUNDLE-PRODUCT-TEST",
"price": {
"currencyCode": "USD",
"amount": 20.79
}
},
"memberAmount": {
"value": 1
}
}
}
},
{
"amount": {
"unit": "ONE",
"value": 2
},
"createdAt": "2022-02-22T16:13:11.798Z",
"product": {
"title": "example-component-product-2-title",
"price": {
"currencyCode": "USD",
"amount": 5
},
"purchaseGroupMembership": {
"product": {
"sku": "BUNDLE-PRODUCT-TEST",
"price": {
"currencyCode": "USD",
"amount": 20.79
}
},
"memberAmount": {
"value": 1
}
}
}
}
],
"orderLinks": [
{
"destinationType": "EXTERNAL_ORDER_MANAGEMENT",
"url": "https://mystore123.com/orders/512968435"
}
]
}
}
}
}
Create an order with items that belong to a bundled product with only the fields required to fulfill the order
The following example shows how to use the createOrder mutation to support bundled product attribution for each line item in the order if the shopper purchases the component as part of a bundled product. When you create the order, in PurchasedProductView specify the optional purchaseGroupMembership field to provide the connection to the bundled product. Within purchaseGroupMembership, use the product field to provide the bundled product view, and use the optional memberAmount field to provide the quantity of the line item attributed to the bundled product.
The following example shows how to create a Buy with Prime order with items that belong to a bundled product while providing only the required fields to fulfill the order.
Request
// GraphQL mutation
mutation createOrder {
createOrder(
input: {
lineItems: [
{
product: {
identifier: {
productId: "example-component-product-1-id"
}
title: "example-component-product-1-title"
price: {
amount: 10.79
currencyCode: "USD"
}
purchaseGroupMembership: {
product: {
identifier: {
sku: "BUNDLE-PRODUCT-TEST"
}
}
}
}
amount: {
value: 1
}
selectedDeliveryOffer: {
details: {
id: "1234567890"
deliveryPreviewId: "SIP-0000000-000000"
deliveryProvider: AMAZON
deliveryTerms: {
isPrimeEligible: true
}
}
}
},
{
product: {
identifier: {
productId: "example-component-product-2-id"
}
title: "example-component-product-2-title"
price: {
amount: 5
currencyCode: "USD"
}
purchaseGroupMembership: {
product: {
identifier: {
sku: "BUNDLE-PRODUCT-TEST"
}
}
}
}
amount: {
value: 2
}
selectedDeliveryOffer: {
details: {
id: "0987654321"
deliveryPreviewId: "SIP-0000000-000000"
deliveryProvider: AMAZON
deliveryTerms: {
isPrimeEligible: true
}
}
}
}
]
customer: {
contact: {
emailData: {
name: "John Smith"
email: "[email protected]"
}
}
}
recipient: {
deliveryAddress: {
name: "John Smith"
streetAddress: "399 Boren Ave N"
locality: "Seattle"
region: "WA"
countryCode: "US"
postalCode: "98109"
}
}
totalPrice: {
value: {
amount: 20.79
currencyCode: "USD"
}
}
orderLinks: [
{
destinationType: EXTERNAL_ORDER_MANAGEMENT
url: "https://mystore123.com/orders/512968435"
}
]
shopperIdentity: {
apayCheckoutSessionId: {
value: "apay-session-id"
externalId: "external-shopper-checkout-session-id"
}
}
}
) {
order {
id
lineItems {
amount {
unit
value
}
createdAt
product {
title
price {
currencyCode
amount
}
purchaseGroupMembership {
product {
sku
}
}
}
}
orderLinks {
destinationType
url
}
}
}
}
Response
{
"data": {
"createOrder": {
"order": {
"id": "322-ABC1-AAAAAA",
"lineItems": [
{
"amount": {
"unit": "ONE",
"value": 1
},
"createdAt": "2022-02-22T16:13:11.798Z",
"product": {
"title": "example-component-product-1-title",
"price": {
"currencyCode": "USD",
"amount": 10.79
},
"purchaseGroupMembership": {
"product": {
"sku": "BUNDLE-PRODUCT-TEST"
}
}
}
},
{
"amount": {
"unit": "ONE",
"value": 2
},
"createdAt": "2022-02-22T16:13:11.798Z",
"product": {
"title": "example-component-product-2-title",
"price": {
"currencyCode": "USD",
"amount": 5
},
"purchaseGroupMembership": {
"product": {
"sku": "BUNDLE-PRODUCT-TEST"
}
}
}
}
],
"orderLinks": [
{
"destinationType": "EXTERNAL_ORDER_MANAGEMENT",
"url": "https://mystore123.com/orders/512968435"
}
]
}
}
}
}
Use a delivery offer to create a Buy with Prime order
The following example shows how to pass a delivery offer to the createOrder mutation. When you create the order, you specify the selectedDeliveryOffer for each line item.
In the DeliveryOfferDetails, make sure to provide both the deliveryPreviewId and the id for accurate representation of the chosen delivery option within the finalized order.
Request
# Variables from sample data
inSearchOfLostTimeBook
deliveryPreviewId
deliveryOfferId
reversalOfferId
janeDoeCustomer
johnDoeRecipient
// GraphQL mutation
mutation createOrder($input: CreateOrderInput) {
createOrder(input: $input) {
order {
id
}
}
}
// Mutation variables
{
"input": {
"desiredExecutionState": "STARTED",
"customer": janeDoeCustomer,
"recipient": johnDoeRecipient,
"lineItems": [
{
"product": {
"productId": productId,
"title": inSearchOfLostTimeBook.title,
"price": {
"currentPrice": {
"amount": inSearchOfLostTimeBook.price.amount,
"currencyCode": inSearchOfLostTimeBook.price.currencyCode
}
}
},
"amount": {
"unit": "UNIT",
"value": 1
},
"selectedDeliveryOffer": {
"details": {
"deliveryPreviewId": deliveryPreviewId,
"id": deliveryOfferId"deliveryProvider": "AMAZON"
}
}
}
],
"shopperIdentity": {
"apayCheckoutSessionId": {
"value": "testToken",
"externalId": "externalId1"
}
}
}
}
Response
orderResponse =
{
"data": {
"order": {
"id": "example-order-id"
}
}
}
Related topics
Updated about 2 hours ago