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.
Updated 2 months ago