Retrieving order status
Ordering API allows you to retrieve the status of an order by calling the orderDetails operation. The API returns item, price, status, and shipping information. Additionally, Ordering API supports an optional subscription to Amazon Simple Notification Service (SNS) that sends you a notification whenever an order is updated, so you can call the API to retrieve the latest status. You can use this data to display up-to-date order information to your customers.
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.
Get order information
To get order information, call the orderDetails operation and pass the order’s externalId in the request.
| Type | Name | Description | Schema | Required |
|---|---|---|---|---|
| Path | externalId | The unique identifier provided by the customer while placing the order. | string | Yes |
| Header | x-amz-user-email | The email address of the user requesting this resource. | string | Yes |
You can only retrieve order details for one
externalIdat a time.
GET/ordering/2022-10-30/orders/externalId-OrderLevel-b-799-791-9962
{ "x-amz-user-email":"[[email protected]]"
}
When an order is placed, the request will (1) identify the externalId of the requesting resource, and (2) check if the email in the API request header has view order access permission that is associated with a business group. If there is no view order access permission, the response will show an “unauthorized user” exception.
A successful request returns details about the items and shipments in the order. For each line item, the API returns accepted items (items that were successfully ordered) and rejected items (items that could not be ordered).
| 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 |
Sample response with view order access permission:
{
"lineItems": [
{
"externalId": "externalID-LineLevel-B01N7KS123",
"acceptedItems": [
{
"quantity": 1,
"artifacts": [
{
"acceptanceArtifactType": "DeliveryTimeRange",
"lowerBoundary": "2023-07-04T03:00:00Z",
"upperBoundary": "2023-07-04T03:00:00Z"
},
{
"acceptanceArtifactType": "UnitPrice",
"amount": {
"currencyCode": "USD",
"amount": 20.49
}
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": -11.24
},
"category": "SHIPPING",
"type": "DISCOUNT"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 20.49
},
"category": "SUBTOTAL",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 11.24
},
"category": "SHIPPING",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 1.69
},
"category": "SUBTOTAL",
"type": "TAX"
},
{
"acceptanceArtifactType": "OrderIdentifier",
"identifier": "113-2725493-02XXXXX"
},
{
"acceptanceArtifactType": "ShipmentGroup",
"identifier": "21946403078XXXX",
"packageReferences": [
{
"packageReferenceType": "CarrierTrackingNumber",
"value": "TBA3074541XXXX"
}
],
"quantity": 1
}
]
}
],
"rejectedItems": []
},
{
"externalId": "externalID-LineLevel-B0BMQG4XXX",
"acceptedItems": [
{
"quantity": 1,
"artifacts": [
{
"acceptanceArtifactType": "DeliveryTimeRange",
"lowerBoundary": "2023-07-04T03:00:00Z",
"upperBoundary": "2023-07-04T03:00:00Z"
},
{
"acceptanceArtifactType": "UnitPrice",
"amount": {
"currencyCode": "USD",
"amount": 5.99
}
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": -0.28
},
"category": "SHIPPING",
"type": "DISCOUNT"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 5.99
},
"category": "SUBTOTAL",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 0.28
},
"category": "SHIPPING",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 0.49
},
"category": "SUBTOTAL",
"type": "TAX"
},
{
"acceptanceArtifactType": "OrderIdentifier",
"identifier": "113-2725493-02XXXXX"
},
{
"acceptanceArtifactType": "ShipmentGroup",
"identifier": "2194640307XXXXC",
"packageReferences": [
{
"packageReferenceType": "CarrierTrackingNumber",
"value": "TBA3074541CCVVFF"
}
],
"quantity": 1
}
]
}
],
"rejectedItems": []
},
{
"externalId": "externalID-LineLevel-B08YJC2XXX",
"acceptedItems": [
{
"quantity": 1,
"artifacts": [
{
"acceptanceArtifactType": "DeliveryTimeRange",
"lowerBoundary": "2023-07-04T03:00:00Z",
"upperBoundary": "2023-07-04T03:00:00Z"
},
{
"acceptanceArtifactType": "UnitPrice",
"amount": {
"currencyCode": "USD",
"amount": 8.82
}
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": -0.12
},
"category": "SHIPPING",
"type": "DISCOUNT"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 8.82
},
"category": "SUBTOTAL",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 0.12
},
"category": "SHIPPING",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 0.73
},
"category": "SUBTOTAL",
"type": "TAX"
},
{
"acceptanceArtifactType": "OrderIdentifier",
"identifier": "113-2725493-02CCCAFA"
},
{
"acceptanceArtifactType": "ShipmentGroup",
"identifier": "219464030TTARFS",
"packageReferences": [
{
"packageReferenceType": "CarrierTrackingNumber",
"value": "TBA3074541VAGSFS"
}
],
"quantity": 1
}
]
}
],
"rejectedItems": []
}
],
"acceptanceArtifacts": [
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": -11.64
},
"category": "SHIPPING",
"type": "DISCOUNT"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 35.3
},
"category": "SUBTOTAL",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 11.64
},
"category": "SHIPPING",
"type": "PRINCIPAL"
},
{
"acceptanceArtifactType": "Charge",
"amount": {
"currencyCode": "USD",
"amount": 2.91
},
"category": "SUBTOTAL",
"type": "TAX"
},
{
"acceptanceArtifactType": "Shipment",
"identifier": "2194640307TSGAH",
"packages": [
{
"packageReference": {
"packageReferenceType": "CarrierTrackingNumber",
"value": "TBA3074541AJSBS"
},
"packageAttributes": [
{
"packageAttributeType": "PackageTrackingAttribute",
"carrierName": "Amazon",
"deliveryDateRange": {
"startDateTime": "2023-07-03T07:00:00Z",
"endDateTime": "2023-07-04T03:00:00Z"
}
}
]
}
]
}
],
"rejectionArtifacts": []
}
Sample response without view order access permission:
{
"errors": [
{
"code": "Unauthorized",
"message": "Unauthorized.",
"details": "Unauthorized user."
}
]
}
Order notifications and updates
Ordering API also supports real-time order updates by subscribing to Amazon SNS. Amazon SNS helps reduce the number of API calls and provides effective resource usage. Each notification contains the following details:
| Name | Description |
|---|---|
externalRequestId | The externalId for the order. This ID can be used to call the orderDetails API operation to retrieve real-time information about the order. |
notificationType | The shipping event that triggered the notification. |
The notificationType field can be used to identify the event that triggered the notification. The following notification types can be returned:
| Value | Description |
|---|---|
OrderUpdated | The quantity for a line item has been updated for the purchase order. |
OrderCancelled | The entire order has been cancelled. |
ShipmentCompleted | Any package in the purchase order has been shipped. |
After you receive a notification, you can call the orderDetails API to retrieve the latest API status.
Sample notification message
{externalRequestId":"externalId-OrderLevel-b-605-663-XXXX",
"notificationType": "ShipmentCompleted"}
How to receive SNS notifications
If you would like to receive order notifications and updates, you’ll need to configure Amazon SNS.
Setup access for Amazon SNS is through AWS console. You will need an AWS account. To create a free AWS account, see AWS Free Tier. To create and activate a new AWS account, see How do I create and activate a new AWS account? If you have an AWS account, you do not need to create a new one.
There’s no cost in setting up access to Amazon SNS, and the subscription cost is based on usage and type of topic. SNS topics are defined as standard topics and FIFO topics. Please refer to Amazon SNS pricing.
Subscription is optional. Accessing and using the Ordering API
orderDetailsoperation is possible without configuring Amazon SNS.
Complete these steps to configure Amazon SNS for order notifications:
Step 1. Create an SNS topic
-
Sign in to AWS.
-
In the search field, enter SNS.
- Select Simple Notification Service. The Amazon SNS page displays.
- Select Create topic. The Create topic page displays.
- In the Name input field, enter the name of the SNS topic.
- Navigate to Access policy.
- Select Advanced.
- In the JSON editor, delete all other permission except for “SNS:Publish”.
- On the bottom of the page, select Create topic. The next page displays a banner informing you that the topic has been created.
Step 2. Create an IAM role
- In the search field, enter IAM.
- Select IAM. The Identify and Access Management (IAM) page displays.
- Select Create policy. The Specify permissions page displays.
- In the search field, enter SNS and select Next.
- From the Access level section, navigate to Write and select Publish.
- Navigate to Resources and select Specific to allow only the created SNS topic.
- Select Add ARN. The Specify ARNs page displays.
- Select This account and enter the resource region, resource topic name and resource ARN in the appropriate fields.
- Select Add ARNs.
- Navigate back to IAM service and select Roles. Once the Roles page displays, select Create role.
- Complete these steps to create a role:
Step 3. Create role
- Select Custom trust policy.
- On the right-hand navigation, select Add.
- In the Add principal pop-up page, select AWS account and root user from the Principal type drop-down list. In the ARN input field, enter the AWS account ID for your corresponding region.
| Region | AWS account ID |
|---|---|
| NA | 833373244525 |
| EU | 547618761301 |
| JP | 2620048206 |
- Select Add principal. Line 7 will display the IAM ARN information you’ve added.
Step 4. Add IAM ARN in SNS topic
- Navigate to Identify and Access Management (IAM) > Access Management > Roles. You’ll see the page for the role you’ve created. In this example, the role is SNS_Role.
- Copy the ARN from IAM role by selecting the (copy) icon. You’ll paste this information the SNS topic.
- Navigate to the SNS topic created earlier, select Edit and replace the “*” with the IAM role ARN.
- On the bottom of the page, select Save changes.
Updated 5 days ago