Placing an order

Ordering API allows your customers to submit Amazon Business purchase orders directly from your purchasing system. Each Ordering API request consists of information about the line items being ordered, attributes related to the order, and customer expectations that must be met for order fulfillment. By integrating Ordering API into your application, you can simplify your system’s buying, approval, and budgeting processes.

Prerequisites

Before starting this tutorial, complete these steps:

Complete the Ordering API partner and customer onboarding process. For more information, see Getting started with Ordering API.
Gain access to the Amazon Business Order Placement role. For more information, see Amazon Business API roles.

Place an Amazon Business order

To place an order, call the placeOrder operation and include the following fields in the request:

Name	Description	Schema	Required
`externalId`	A customer-specified identifier that must be unique for each order. This value is often machine-generated. Amazon Business uses this value to identify unique order requests.	string	Yes
`lineItems`	Items in the order.	< RequestLineItem > array	Yes
`attributes`	Customer-determined order properties.	< Attribute > array	Yes
`expectations`	Customer expectations about aspects of an order they do not directly control.	< Expectation > array	Yes

Attributes can be provided at the order level (in the attributes object) and line item level (in the lineItems object). Similarly, expectations can be provided at the order level (within the expectations object) and the line item level (within the lineItems object). This placement determines whether the attribute or expectation applies to the entire order, or only to a specific line item.

Ordering API is polymorphic, meaning that there can be many specific subtypes of an attribute or expectation. Subtypes are identified by expectationType for expectations and attributeType for attributes. When a subtype is provided in a request, additional fields need to be included within the object as determined by the attribute or expectation type’s specification. For example, if expectationType is ExpectedCharge, then amount and source fields also need to be included within the object.

📘
Amazon Business can add new values for discriminator fields, such as acceptance artifacts, rejection artifacts, attributes, and expectations, to the API request or response at any time. Your integration will continue to function without incorporating these new fields.

Ordering API will place an order if all the expectations in the request are met at processing time. This logic works in conjunction with order safeguards. For more information on how safeguards affect order fulfillment, see Safeguards.

Required attributes

To place an order, these attributes must be included in the request:

Attribute	Description	Required at
`Region`	The country or region where the buyer places an order.	Order level
`SelectedPaymentMethodReference`	The payment method where the charges for the order will apply. Set `paymentMethodReferenceType` to `StoredPaymentMethod` to use the payment method that is stored on your Amazon Business group.	Order level
`BuyingGroupReference`	A reference to the buying group associated with an order request. In the `groupReference` object, set `groupReferenceType` to `GroupIdentity` and provide the group ID in the `identifier` field.	Order level
`BuyerReference`	A reference to the buying customer. In the userReference object, set `userReferenceType` to `UserEmail` and provide the buyer's email in the `emailAddress` field.	Order level
`ShippingAddress`	Indicates where to ship the order.	Order level or at each line item
`SelectedProductReference`	Contains a reference to the product to order. Set `productReferenceType` to `ProductIdentifier` and provide the ASIN for the desired product in the `id` field.	Order level or line item level
`PurchaseOrderNumber`	A reference to the purchase order form of the order request. Limit the number of characters to 30.	Order level

Optional attributes

The following attributes can optionally be included in your request:

Attribute	Description	Required at
`TrialMode`	Indicates that an order is a trial order. The steps to place an order will be completed, but no actual order will be created.	Order level
`SelectedBuyingOptionReference` (OfferID)	Contains a reference to the buying option to order. In most cases, this field contains the offer ID. While this attribute is optional, it is strongly recommended to be included in your Ordering API requests. When this field is provided, Ordering API will prioritize this buying option among other available options for the requested product.	Order level or line item level
`BillingAddress`	The customer-provided billing address for a specific transaction that only uses Pay by Invoice (PBI) as the payment method. When no billing address is specified in this field, the API returns the default address specified on Amazon Business PBI payment method.	Order level
`Auxiliary`	Additional fields for customers to send additional information for pre- or post-order processing. This object contains key/value pairs that can vary depending on the use case.	Order level

Expectations

If order safeguards are enabled for the Amazon Business group used to place the order, the following expectations must be included in the request:

Expectation	Description	Required at
`ExpectedUnitPrice`	The unit price value the customer expects for an item. If passed at order level, the expected monetary charge will apply to all line items that has no set expectation. Note: This expectation is only required if the price safeguard is enabled.	Order level or line item level
`ExpectedCharge`	The monetary charge that is expected for an item or order. If passed at order level, the expected monetary charge will apply to all line items that has no set expectation.	Order level or line item level

🚧
If order safeguards are not configured for the group, expectations are not required in the request. Without safeguards, Ordering API will select and charge the featured offer (default buying option for a product) on the Amazon Business website). It is recommended to use safeguards to protect from dramatic price increases, longer delivery times, and low stock levels. For more information, see Using order safeguards.

POST https://na.business-api.amazon.com/ordering/2022-10-30/orders
{
  "externalId": "external-order-id-12345",
  "lineItems": [
    {
      "externalId": "line-item-1",
      "quantity": 1,
      "attributes": [
        {
          "attributeType": "SelectedProductReference",
          "productReference": {
            "productReferenceType": "ProductIdentifier",
            "id": "[ASIN]"
          }
        },
        {
          "attributeType": "SelectedBuyingOptionReference",
          "buyingOptionReference": {
            "buyingOptionReferenceType": "BuyingOptionIdentifier",
            "id": "[Offer ID]"
          }
        }
      ],
      "expectations": [
        {
          "expectationType": "ExpectedUnitPrice",
          "amount": {
            "currencyCode": "USD",
            "amount": 10.00
          }
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 10.00
          },
          "source": "SUBTOTAL"
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 0.50
          },
          "source": "TAX"
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 5.00
          },
          "source": "SHIPPING"
        }
      ]
    }
  ],
  "attributes": [
    {
      "attributeType": "PurchaseOrderNumber",
      "purchaseOrderNumber": "ExamplePurchaseOrderNumber"
    },
    {
      "attributeType": "BuyerReference",
      "userReference": {
        "userReferenceType": "UserEmail",
        "emailAddress": "[email protected]"
      }
    },
    {
      "attributeType": "BuyingGroupReference",
      "groupReference": {
        "groupReferenceType": "GroupIdentity",
        "identifier": "ExampleGroup"
      }
    },
    {
      "attributeType": "Region",
      "region": "US"
    },
    {
      "attributeType": "SelectedPaymentMethodReference",
      "paymentMethodReference": {
        "paymentMethodReferenceType": "StoredPaymentMethod"
      }
    },
    {
      "attributeType": "ShippingAddress",
      "address": {
        "addressType": "PhysicalAddress",
        "fullName": "Example User",
        "phoneNumber": "1234567890",
        "companyName": "Example Company",
        "addressLine1": "123 Example St.",
        "addressLine2": "456",
        "city": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98109",
        "countryCode": "US"
      }
    }
  ],
  "expectations": []
}

import requests

url = "https://na.business-api.amazon.com/ordering/2022-10-30/orders"

payload = {
{
  "externalId": "external-order-id-12345",
  "lineItems": [
{
      "externalId": "line-item-1",
      "quantity": 1,
      "attributes": [
        {
          "attributeType": "SelectedProductReference",
          "productReference": {
            "productReferenceType": "ProductIdentifier",
            "id": "[ASIN]"
          }
        }
        {
          "attributeType": "SelectedBuyingOptionReference",
          "buyingOptionReference": {
            "buyingOptionReferenceType": "BuyingOptionIdentifier",
            "id": "[Offer ID]"
          }
        }
      ],
      "expectations": [
        {
          "expectationType": "ExpectedUnitPrice",
          "amount": {
            "currencyCode": "USD",
            "amount": 10.00
          }
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 10.00
          },
          "source": "SUBTOTAL"
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 0.50
          },
          "source": "TAX"
        },
        {
          "expectationType": "ExpectedCharge",
          "amount": {
            "currencyCode": "USD",
            "amount": 5.00
          },
          "source": "SHIPPING"
        }
      ]
    }
  ],
  "attributes": [
    {
      "attributeType": "PurchaseOrderNumber",
      "purchaseOrderNumber": "ExamplePurchaseOrderNumber"
    },
    {
      "attributeType": "BuyerReference",
      "userReference": {
        "userReferenceType": "UserEmail",
        "emailAddress": "[email protected]"
      }
    },
    {
      "attributeType": "BuyingGroupReference",
      "groupReference": {
        "groupReferenceType": "GroupIdentity",
        "identifier": "ExampleGroup"
      }
    },
    {
      "attributeType": "Region",
      "region": "US"
    },
    {
      "attributeType": "SelectedPaymentMethodReference",
      "paymentMethodReference": {
      "paymentMethodReferenceType": "StoredPaymentMethod"
      }
    },
    {
      "attributeType": "ShippingAddress",
      "address": {
        "addressType": "PhysicalAddress",
        "fullName": "Example User",
        "phoneNumber": "1234567890",
        "companyName": "Example Company",
        "addressLine1": "123 Example St.",
        "addressLine2": "456",
        "city": "Seattle",
        "stateOrRegion": "WA",
        "postalCode": "98109",
        "countryCode": "US"
      }
    }
  ],
  "expectations": []
}
}
headers = {
    "accept": "application/json",
    "x-amz-access-token": "<Access token retrieved in Prerequisites Step 1>",
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Upon receiving a successful request, Ordering API processes the line items in the request to see if they can be successfully fulfilled given the attributes and expectations defined in the request. The resulting response includes the line items from the request, broken down into accepted and rejected items.

📘
The quantity in a request line item will match the total quantity across the corresponding result line item's accepted and rejected items. For instance, if a line item has a requested quantity of 5 but Ordering API can only fulfill 3 quantity, the response will return an accepted quantity of 3 and rejected quantity of 2.

In the following example, the entire order could be successfully fulfilled and no line items were rejected.

A successful request returns the following fields:

Name	Description	Schema
`lineItems`	Order results for specific line items.	< ResultLineItem > array
`acceptanceArtifacts`	Results of a successful order.	< AcceptanceArtifact > array
`rejectionArtifacts`	Reasons the order was rejected.	< RejectionArtifact > array

{
  "lineItems": [
    {
      "externalId": "external-order-id-12345",
      "acceptedItems": [
        {
          "quantity": 1,
          "artifacts": [
            {
              "acceptanceArtifactType": "DeliveryTimeRange",
              "lowerBoundary": "2023-01-01T08:00:00Z",
              "upperBoundary": "2023-01-02T07:59:59Z"
            },
            {
              "acceptanceArtifactType": "UnitPrice",
              "amount": {
                "currencyCode": "USD",
                "amount": 9.99
              }
            },
            {
              "acceptanceArtifactType": "Charge",
              "amount": {
                "currencyCode": "USD",
                "amount": 4.99
              },
              "category": "SHIPPING",
              "type": "PRINCIPAL"
            },
            {
              "acceptanceArtifactType": "Charge",
              "amount": {
                "currencyCode": "USD",
                "amount": 9.99
              },
              "category": "SUBTOTAL",
              "type": "PRINCIPAL"
            },
            {
              "acceptanceArtifactType": "OrderIdentifier",
              "identifier": "000-1111111-2222222"
            }
          ]
        }
      ],
      "rejectedItems": []
    }
  ],
  "acceptanceArtifacts": [
    {
      "acceptanceArtifactType": "Charge",
      "amount": {
        "currencyCode": "USD",
        "amount": 4.99
      },
      "category": "SHIPPING",
      "type": "PRINCIPAL"
    },
    {
      "acceptanceArtifactType": "Charge",
      "amount": {
        "currencyCode": "USD",
        "amount": 9.99
      },
      "category": "SUBTOTAL",
      "type": "PRINCIPAL"
    },
    {
      "acceptanceArtifactType": "Signed"
    }
  ],
  "rejectionArtifacts": []
}

Error handling

If your request is not successful, the API returns an errors object that provides information about what went wrong. For more information, see Error responses and schemas.

If the API input is valid but the order cannot be fulfilled due to service issues or business logic reasons, then the API returns an HTTP 200 status code with a rejection code in the API response body. For more information, see Ordering API rejection codes.