Orders API v0 Use Case Guide
Improve order inventory synchronization, workflows, and reporting tools.
API Version: v0
What is the Orders API?
Use the Orders API to programmatically retrieve and submit order information. This API is designed to help Selling Partners develop fast and flexible custom applications that facilitate order synchronization, order research, and demand-based decision support tools.
Note
Orders more than two years old will not show in the API response, except for the SG, JP, and AU marketplaces, which support orders from 2016 and after.
For information about authentication and authorization, refer to Authorizing Selling Partner API Applications. For information about regulated orders, refer to the Regulated Orders guide.
Key features
- Retrieve orders information with filtering criteria: The
getOrders
operation of the Orders API returns orders created or updated during the time frame or other filtering criteria indicated by the specified parameters. IfNextToken
is present, it is used to retrieve the orders instead of other criteria. - Retrieve specified order information: The
getOrder
operation of the Orders API returns order information that you specify. - Retrieve order item information for the specified order: The
getOrderItems
operation of the Orders API returns detailed order item information for the order that you specify. IfNextToken
is provided, it is used to retrieve the next page of order items. - Confirm shipment for the specified order: The
confirmShipment
operation of the Orders API confirms the shipment status for a specified order. It can also be used to edit shipment details of orders that have been shipped.
Tutorial 1: Retrieve orders information with filtering criteria
The getOrders
operation of the Orders API returns orders created or updated during the time frame or other filtering criteria indicated by the specified parameters. If NextToken
is present, that will be used to retrieve the orders instead of other criteria.
Warning
The
getOrders
operation has a systematic delay in data retrieval. Most updated orders data will be available 2 minutes after an order is created or last updated. To ensure that you retrieve the latest orders data, call the operation 2 minutes after the order is created or updated.
Prerequisites
To successfully complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
- Approval for the Inventory and Order Tracking role in your developer profile.
- The Inventory and Order Tracking role selected in the App registration page for your application.
To access buyer and shipping address information, you must:
-
Have approval for the following roles:
- Direct-to-Consumer Delivery (Restricted) role is required to access shipping address information.
- The Tax Remittance (Restricted) role is required to access buyer information.
- The Tax Invoicing (Restricted) role is required to access buyer information.
-
Use a Restricted Data Token (RDT)
- Follow the Tutorial: Get authorization to access PII for bulk orders to get an RDT that provides authorization to access Personally Identifiable Information (PII) for bulk orders.
- Use any of the following values in the
dataElements
parameter in thecreateRestrictedDataToken
operation to access thegetOrders
operation:buyerInfo
shippingAddress
buyerTaxInformation
getOrders Request
Call the getOrders
operation.
Query parameters
Name | Description | Required |
---|---|---|
CreatedAfter | A date used for selecting orders created after (or at) a specified time. Only orders placed after the specified time are returned. You must provide either the CreatedAfter parameter or the LastUpdatedAfter parameter. If both are empty the call is invalid. | No |
CreatedBefore | A date used for selecting orders created before (or at) a specified time. Only orders placed before the specified time are returned. The date must be in ISO 8601 format. | No |
LastUpdatedAfter | A date used for selecting orders that were last updated after (or at) a specified time. An update is defined as any change in order status, including the creation of a new order. Includes updates made by Amazon and by the seller. The date must be in ISO 8601 format. You must provide either the CreatedAfter parameter or the LastUpdatedAfter parameter. If both are empty the call is invalid. | No |
LastUpdatedBefore | A date used for selecting orders that were last updated before (or at) a specified time. An update is defined as any change in order status, including the creation of a new order. Includes updates made by Amazon and by the seller. The date must be in ISO 8601 format. | No |
OrderStatuses | A list of OrderStatus values used to filter the results.Possible values: - PendingAvailability (This status is available for pre-orders only. The order has been placed, payment has not been authorized, and the release date of the item is in the future.)- Pending (The order has been placed but payment has not been authorized.)- Unshipped (Payment has been authorized and the order is ready for shipment, but no items in the order have been shipped.)- PartiallyShipped (One or more, but not all, items in the order have been shipped.)- Shipped (All items in the order have been shipped.)- InvoiceUnconfirmed (All items in the order have been shipped. The seller has not yet given confirmation to Amazon that the invoice has been shipped to the buyer.)- Canceled (The order has been canceled.)- Unfulfillable (The order cannot be fulfilled. This state applies only to Multi-Channel Fulfillment orders.) | No |
MarketplaceIds | A list of MarketplaceId values. Used to select orders that were placed in the specified marketplaces.br>Refer to Marketplace IDs for a complete list of marketplaceId values.Max count : 50 | Yes |
FulfillmentChannels | A list that indicates how an order was fulfilled. Filters the results by fulfillment channel. Possible values: AFN (Fulfillment by Amazon); MFN (Fulfilled by the seller). | No |
PaymentMethods | A list of payment method values. Used to select orders paid using the specified payment methods. Possible values: COD (Cash on delivery); CVS (Convenience store payment); Other (Any payment method other than COD or CVS). | No |
BuyerEmail | The email address of a buyer. Used to select orders that contain the specified email address. | No |
SellerOrderId | An order identifier that is specified by the seller. Used to select only the orders that match the order identifier. If SellerOrderId is specified, then FulfillmentChannels , OrderStatuses , PaymentMethod , LastUpdatedAfter , LastUpdatedBefore , and BuyerEmail cannot be specified. | No |
MaxResultsPerPage | A number that indicates the maximum number of orders that can be returned per page. Value must be 1 - 100. Default 100. | No |
EasyShipShipmentStatuses | A list of EasyShipShipmentStatus values. Used to select Easy Ship orders with statuses that match the specified values. If EasyShipShipmentStatus is specified, only Amazon Easy Ship orders are returned.Possible values: - PendingSchedule (The package is awaiting the schedule for pick-up.)- PendingPickUp (Amazon has not yet picked up the package from the seller.)- PendingDropOff (The seller will deliver the package to the carrier.)- LabelCanceled (The seller canceled the pickup.)- PickedUp (Amazon has picked up the package from the seller.)- DroppedOff (The package is delivered to the carrier by the seller.)- AtOriginFC (The packaged is at the origin fulfillment center.)- AtDestinationFC (The package is at the destination fulfillment center.)- Delivered (The package has been delivered.)- RejectedByBuyer (The package has been rejected by the buyer.)- Undeliverable (The package cannot be delivered.)- ReturningToSeller (The package was not delivered and is being returned to the seller.)- ReturnedToSeller (The package was not delivered and was returned to the seller.)- Lost (The package is lost.)- OutForDelivery (The package is out for delivery.)- Damaged (The package was damaged by the carrier.) | No |
ElectronicInvoiceStatuses | A list of ElectronicInvoiceStatus values. Used to select orders with electronic invoice statuses that match the specified values.Possible values: - NotRequired (Electronic invoice submission is not required for this order.)- NotFound (The electronic invoice was not submitted for this order.)- Processing (The electronic invoice is being processed for this order.)- Errored (The last submitted electronic invoice was rejected for this order.)- Accepted (The last submitted electronic invoice was submitted and accepted.) | No |
NextToken | A string token returned in the response of your previous request. | No |
AmazonOrderIds | A list of AmazonOrderId values. An AmazonOrderId is an Amazon-defined order identifier, in 3-7-7 format.Max count : 50 | No |
ActualFulfillmentSupplySourceId | Denotes the recommended sourceId where the order should be fulfilled from. | No |
IsISPU | When true, this order is marked to be picked up from a store rather than delivered. | No |
StoreChainStoreId | The store chain store identifier. Linked to a specific store in a store chain. | No |
Request example
GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders?
MarketplaceIds=ATVPDKIKX0DER
&CreatedAfter=2020-10-10
&MaxResultPerPage=2
Response
A successful response includes the following:
Name | Description | Required |
---|---|---|
Orders | A list of orders. Type: Order array | Yes |
NextToken | When present and not empty, pass this string token in the next request to return the next response page. | No |
LastUpdatedBefore | A date used for selecting orders that were last updated before (or at) a specified time. An update is defined as any change in order status, including the creation of a new order. Includes updates made by Amazon and by the seller. All dates must be in ISO 8601 format. | No |
CreatedBefore | A date used for selecting orders created before (or at) a specified time. Only orders placed before the specified time are returned. The date must be in ISO 8601 format. | No |
Response examples
The following is an example of a general response from the getOrders
operation.
{
"payload": {
"NextToken": "2YgYW55IGNhcm5hbCBwbGVhc3VyZS4",
"Orders": [
{
"AmazonOrderId": "902-3159896-1390916",
"PurchaseDate": "2017-01-20T19:49:35Z",
"LastUpdateDate": "2017-01-20T19:49:35Z",
"OrderStatus": "Pending",
"FulfillmentChannel": "SellerFulfilled",
"NumberOfItemsShipped": 0,
"NumberOfItemsUnshipped": 0,
"PaymentMethod": "Other",
"PaymentMethodDetails": [
"CreditCard",
"GiftCertificate"
],
"MarketplaceId": "ATVPDKIKX0DER",
"ShipmentServiceLevelCategory": "Standard",
"OrderType": "StandardOrder",
"EarliestShipDate": "2017-01-20T19:51:16Z",
"LatestShipDate": "2017-01-25T19:49:35Z",
"IsBusinessOrder": false,
"IsPrime": false,
"IsAccessPointOrder": false,
"IsGlobalExpressEnabled": false,
"IsPremiumOrder": false,
"IsSoldByAB": false,
"IsIBA": false,
"ShippingAddress": {
"Name": "Michigan address",
"AddressLine1": "1 Cross St.",
"City": "Canton",
"StateOrRegion": "MI",
"PostalCode": "48817",
"CountryCode": "US"
},
"BuyerInfo": {
"BuyerEmail": "[email protected]",
"BuyerName": "John Doe",
"BuyerTaxInfo": {
"CompanyLegalName": "A Company Name"
},
"PurchaseOrderNumber": "1234567890123"
}
}
]
}
}
When an order is shipped to a Brazil address, you might also receive additional address fields, (for example, StreetName, StreetNumber, Complement, and Neighborhood) as shown in the following example.
{
"ShippingAddress": {
"Name": "Brazil address",
"AddressLine1": "Street 9 450",
"AddressLine2": "Suite 30 Central",
"ExtendedFields": {
"StreetName": "Street 9",
"StreetNumber": "450",
"Complement": "Suite 30",
"Neighborhood": "Central"
},
"City": "Rio de Janeiro",
"StateOrRegion": "RJ",
"PostalCode": "48817",
"CountryCode": "BR"
}
}
For more information on when shipping addresses contain extended fields, refer to the Order
schema in the Orders API v0 reference.
For a list of possible extended fields, refer to AddressExtendedFields
in the Orders API v0 reference.
Tutorial 2: Retrieve order information
The tutorial shows you how to use the getOrder
operation of the Orders API to retrieve order information that you specify.
Prerequisites
To successfully complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
- Approval for the Inventory and Order Tracking role in your developer profile.
- The Inventory and Order Tracking role selected in the App registration page for your application.
To access buyer and shipping address information, you must:
-
Have approval for the following roles:
- Direct-to-Consumer Delivery (Restricted) role is required to access shipping address information.
- The Tax Remittance (Restricted) role is required to access buyer information.
- The Tax Invoicing (Restricted) role is required to access buyer information.
-
Use a Restricted Data Token (RDT):
- Follow the Tokens API Use Case Guide to get an RDT that provides authorization to access Personally Identifiable Information (PII) for an operation.
- Use any of the following values in the
dataElements
parameter in thecreateRestrictedDataToken
operation to access thegetOrder
operation:buyerInfo
shippingAddress
buyerTaxInformation
Request
Parameter | Description | Required |
---|---|---|
orderId
|
An Amazon-defined order identifier, in 3-7-7 format.
Type: string |
Yes |
Request example
GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/
Response
A successful response includes the following:
Name | Description | Required |
---|---|---|
Order | Order information. Type: Order | Yes |
Refer to Order
in the API reference for details about the possible objects and properties in an order.
Response example
{
"payload": {
"BuyerInfo": {},
"AmazonOrderId": "026-1520163-6049104",
"EarliestShipDate": "2022-03-10T00:00:00Z",
"SalesChannel": "Amazon.co.uk",
"AutomatedShippingSettings": {
"HasAutomatedShippingSettings": false
},
"OrderStatus": "Canceled",
"NumberOfItemsShipped": 0,
"OrderType": "StandardOrder",
"IsPremiumOrder": false,
"IsPrime": false,
"FulfillmentChannel": "MFN",
"NumberOfItemsUnshipped": 0,
"HasRegulatedItems": true,
"IsReplacementOrder": false,
"IsSoldByAB": false,
"LatestShipDate": "2022-03-10T23:59:59Z",
"ShipServiceLevel": "Std UK Dom_1",
"IsISPU": false,
"MarketplaceId": "A1F83G8C2ARO7P",
"PurchaseDate": "2022-03-09T22:03:02Z",
"IsAccessPointOrder": false,
"IsBusinessOrder": false,
"OrderTotal": {
"CurrencyCode": "GBP",
"Amount": "20.00"
},
"PaymentMethodDetails": [
"Standard"
],
"IsGlobalExpressEnabled": false,
"LastUpdateDate": "2022-03-14T22:05:14Z",
"ShipmentServiceLevelCategory": "Standard"
}
}
Tutorial 3: Retrieve detailed order item information
The tutorial shows you how to use the getOrderItems
operation of the Orders API to retrieve order information that you specify.
Prerequisites
To successfully complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
- Approval for the Inventory and Order Tracking role in your developer profile.
- The Inventory and Order Tracking role selected in the App registration page for your application.
To access buyer and shipping address information, you must:
-
Have approval for the following roles:
- Direct-to-Consumer Delivery (Restricted) role is required to access shipping address information.
- The Tax Remittance (Restricted) role is required to access buyer information.
- The Tax Invoicing (Restricted) role is required to access buyer information.
-
Use a Restricted Data Token (RDT)
- Follow the Tutorial: Get authorization to access PII for the order items in an order to get an RDT that provides authorization to access Personally Identifiable Information (PII) for the order items in an order.
- Use
buyerInfo
as a value in thedataElements
parameter in thecreateRestrictedDataToken
operation to access thegetOrderItems
operation.
Request
Type | Parameter | Description | Required |
---|---|---|---|
Path |
orderId
|
An Amazon-defined order identifier, in 3-7-7 format.
Type: string |
Yes |
Query |
NextToken
|
A string token returned in the response of your previous request.
Type: string |
No |
Request example
GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/902-9855239-8990202/orderItems
Response
A successful response includes the following:
Name | Description | Required |
---|---|---|
OrderItems | A list of order items. Type: OrderItem array | Yes |
NextToken | When present and not empty, pass this string token in the next request to return the next response page. | No |
AmazonOrderId | An Amazon-defined order identifier, in 3-7-7 format. | Yes |
Response example
{
"payload": {
"OrderItems": [
{
"TaxCollection": {
"Model": "MarketplaceFacilitator",
"ResponsibleParty": "Amazon Services, Inc."
},
"ProductInfo": {
"NumberOfItems": "1"
},
"BuyerInfo": {},
"ItemTax": {
"CurrencyCode": "USD",
"Amount": "1.13"
},
"QuantityShipped": 1,
"BuyerRequestedCancel": {
"IsBuyerRequestedCancel": "false",
"BuyerCancelReason": ""
},
"ItemPrice": {
"CurrencyCode": "USD",
"Amount": "11.00"
},
"ASIN": "B004RKQM8I",
"SellerSKU": "AN-M9GI-4QE5",
"Title": "Sony MDR-ZX100 ZX Series Headphones (White)",
"IsGift": "false",
"ConditionSubtypeId": "Acceptable",
"IsTransparency": false,
"QuantityOrdered": 1,
"PromotionDiscountTax": {
"CurrencyCode": "USD",
"Amount": "0.00"
},
"AmazonPrograms": {
"Programs": ["SUBSCRIBE_AND_SAVE"]
},
"ConditionId": "Used",
"PromotionDiscount": {
"CurrencyCode": "USD",
"Amount": "0.00"
},
"OrderItemId": "43345934312798"
}
],
"AmazonOrderId": "902-0300094-5705429"
}
}
Tutorial 4: Confirm a shipment
This tutorial shows you how to confirm a shipment with the confirmShipment
operation after you receive a notification that your order is ready to be fulfilled. You will not need to confirm the shipment if you purchase a shipping label through the Shipping API or buy-shipping UI. The confirmShipment
operation supports all use cases that were supported in the Order Fulfillment Feeds, including supporting multiple tracking IDs per order. To submit multiple package tracking IDs, you will need to send multiple requests with the same order ID but different package reference IDs.
Example:
Call
|
OrderID
|
PackageReferenceId
|
---|---|---|
1st Call | 902-0300094-570542 | 101 |
2st Call | 902-0300094-570542 | 102 |
The package reference ID supports any positive numerical value and is meant for the purpose of editing a shipment after you have confirmed a shipment. You can submit any numerical value as packageReferenceID
and we will store the data. If you need to make an edit to the shipment, submit another confirmShipment
operation with the same packageReferenceID
. The other shipment details will be edited upon successful submission. If you do not put any ID when you submit, Amazon will automatically assign a packageReferenceID
.
Prerequisites
To successfully complete this tutorial, you must have:
- Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
- Approval for the Inventory and Order Tracking role in your developer profile.
- The Inventory and Order Tracking role selected in the App registration page for your application.
If you have been approved for the Direct-to-Consumer Delivery (Restricted) role, you will have access to the confirmShipment
operation.
Step 1. Confirm a shipment for one order
Call the confirmShipment
operation, passing the following parameters:
Path parameters
Parameter | Description | Required |
---|---|---|
orderId
|
An Amazon-defined order identifier, in 3-7-7 format.
Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
packageDetail | Properties of packages Type PackageDetail | Yes |
codCollectionMethod | The cod collection method, support in JP only. Type CodCollectionMethod | No |
marketplaceId | The unobfuscated marketplace identifier. Type MarketplaceId | Yes |
Request example
POST https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/shipmentConfirmation
{
"marketplaceId": "ATVPDKIKX0DER",
"codCollectionMethod": "",
"packageDetail": {
"packageReferenceId": "123",
"carrierCode": "UPS",
"carrierName": "UPS",
"shippingMethod": "SHIPPING",
"trackingNumber": "1Z86V8030385598957",
"shipDate": "2022-11-30T16:15:30Z",
"shipFromSupplySourceId": "057d3fcc-b750-419f-bbcd-4d340c60c430",
"orderItems": [
{
"orderItemId": "60696125413094",
"quantity": 1
}
]
}
}
Response
Response properties:
HTTP code | Description | Schema |
---|---|---|
204 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | No Content |
For error status codes, descriptions and schemas, refer to Confirm Shipment Error Response.
Tip
To confirm multiple orders, use the Feeds API v2021-06-30 and pass the
POST_ORDER_FULFILLMENT_DATA
feed type. For more information, refer to Confirm multiple orders through the Order Fulfillment feed.
Step 2. Edit shipping information for one order
After Step 1, a package is created for the order. You can edit the shipping information like Ship date, Carrier, Shipping service (or Ship method), Tracking ID (supplied by the carrier) by calling the confirmShipment
operation again.
Parameters that need to be consistent
To ensure that you are editing the same shipment, do not change the following parameters.
Parameter | Description | In |
---|---|---|
orderId
|
An Amazon-defined order identifier, in 3-7-7 format.
Type: string |
Path |
packageReferenceId
|
A seller-supplied identifier that uniquely identifies a package within the scope of an order. Note that only a positive numeric value is supported."
Type: string |
PackageDetail |
orderItemId
|
The unique identifier of the order item.
Type: string |
ConfirmShipmentOrderItem |
quantity
|
The quantity of the item.
Type: integer |
ConfirmShipmentOrderItem |
Request example
POST https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/shipmentConfirmation
{
"marketplaceId": "ATVPDKIKX0DER",
"codCollectionMethod": "",
"packageDetail": {
"packageReferenceId": "123",
"carrierCode": "USPS",
"carrierName": "USPS",
"shippingMethod": "SHIPPING",
"trackingNumber": "1Z86V8030385598957",
"shipDate": "2022-11-30T20:15:30Z",
"shipFromSupplySourceId": "057d3fcc-b750-419f-bbcd-4d340c60c430",
"orderItems": [
{
"orderItemId": "60696125413094",
"quantity": 1
}
]
}
}
Response
Response properties:
HTTP code | Description | Schema |
---|---|---|
204 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | No Content |
For error status codes, descriptions and schemas, refer to Error responses and schemas.
Updated 27 days ago