Using order safeguards
Order safeguards determine how Amazon Business handles orders when item pricing and availability change. Setting order safeguards and tolerance limits allows Amazon Business to take an automated action on your behalf if an order does not meet your requirements. For example, you can set a safeguard that removes an item from your order or cancels the entire order if the price increases by more than 20%. By configuring order safeguards for your Ordering API group, you can avoid dramatic price increases.
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.
Step 1. Set safeguards
Your Amazon Business account admin should complete the following steps to configure order safeguards for your Ordering API group:
- In your Amazon Business account, navigate to Business Settings.
- Under System Integrations, select Purchasing system.
- Under Order safeguards, select Edit.
- Set your desired order safeguards in the New value column. For this example, we’ll set price tolerance to 20%.
- Select Save.
Step 2. Send expectations in Ordering API requests
You can start applying safeguards to your Ordering API orders by sending expectations in your requests. Expectations ensure that the item price, item subtotal, and order subtotal aligns are equal to or less than the tolerances defined in your safeguards.
To successfully set expectations that support your safeguards, follow these steps:
- Pass the price you expect to pay in the Ordering API request. For example, if you want to order a $10.00 USD pack of pencils and have the item price tolerance set to 20%, pass
10.00in theExpectedUnitPriceattribute. Given this price tolerance, Ordering API will fulfill the order so long as the unit price does not exceed $12.00 USD (a 20% increase from the expected $10.00 price). - Call the
placeOrderoperation with the appropriateexpectationfields and values.
For general instructions on sending a successful Ordering API request, see Placing an order.
{
"externalId": "externalId1234567890",
"lineItems": [
{
"externalId": 10,
"quantity": 1,
"attributes": [
{
"attributeType": "SelectedProductReference",
"productReference": {
"id": "B09NWB5VJP",
"productReferenceType": "ProductIdentifier"
}
},
{
"attributeType": "SelectedBuyingOptionReference",
"buyingOptionReference": {
"id": "1234561234",
"buyingOptionReferenceType": "BuyingOptionIdentifier"
}
}
],
"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": 5.00
},
"source": "TAX"
},
{
"expectationType": "ExpectedCharge",
"amount": {
"currencyCode": "USD",
"amount": 4.00
},
"source": "SHIPPING"
}
]
}
],
"attributes": [
{
"attributeType": "PurchaseOrderNumber",
"purchaseOrderNumber": "OrderNumber"
},
{
"attributeType": "BuyingGroupReference",
"groupReference": {
"groupReferenceType": "GroupIdentity",
"identifier": "Groupidentity123ABC"
}
},
{
"attributeType": "Region",
"region": "US"
},
{
"attributeType": "SelectedPaymentMethodReference",
"paymentMethodReference": {
"paymentMethodReferenceType": "StoredPaymentMethod"
}
},
{
"attributeType": "ShippingAddress",
"address": {
"addressType": "PhysicalAddress",
"fullName": "Jane Doe",
"phoneNumber": "1231234560",
"companyName": "",
"addressLine1": "123 Any Street",
"addressLine2": "",
"city": "Any Town",
"stateOrRegion": "WA",
"postalCode": "12312",
"countryCode": "US"
}
}
],
"expectations": [
{
"expectationType": "ExpectedUnitPrice",
"amount": {
"currencyCode": "USD",
"amount": 2400
}
},
{
"expectationType": "ExpectedCharge",
"amount": {
"currencyCode": "USD",
"amount": 5000
},
"source": "SUBTOTAL"
},
{
"expectationType": "ExpectedCharge",
"amount": {
"currencyCode": "USD",
"amount": 2000
},
"source": "TAX"
},
{
"expectationType": "ExpectedCharge",
"amount": {
"currencyCode": "USD",
"amount": 1000
},
"source": "SHIPPING"
}
]
}
Ordering API will place the order if the item price, subtotal, and order total are equal to or less than the values provided in the expectations. A successful response will return information about the order, including the actual unit prices and item subtotals. In the following example, we can see that the ExpectedUnitPrice and ExpectedCharge fields returned in the response are 10.00, indicating that Ordering API could successfully fill the order at the expected unit price. If the prices were above the expectations and the safeguard price tolerance, Ordering API would reject the request and return the line items in the rejectionArtifacts object.
{
"lineItems": [
{
"externalId": "10",
"acceptedItems": [
{
"quantity": 1,
"artifacts": [
{
"acceptanceArtifactType": "DeliveryTimeRange",
"lowerBoundary": "2025-05-05T07:00:00Z",
"upperBoundary": "2025-05-06T06:59:59Z"
},
{
"acceptanceArtifactType": "UnitPrice",
"amount": {
"currencyCode": "USD",
"amount":10.00
}
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount":10.00
},
"category": "SUBTOTAL",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "OrderIdentifier",
"identifier": "112-4403676-1234567"
}
]
}
],
"rejectedItems": []
}
],
"acceptanceArtifacts": [
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 11.99
},
"category": "SUBTOTAL",
"type": "PRINCIPAL"
}
],
"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