Amazon Services
Amazon Marketplace Web Service (Amazon MWS) Documentation

Deprecation Notice:

Amazon Marketplace Web Service (MWS) will no longer be available after March 31, 2024. All MWS developers must migrate to Selling Partner API (SP-API) to avoid service disruptions. Refer to the Migration Hub for more information.

Amazon MWS Documentation

ListOrders

Returns orders created or updated during a time frame that you specify.

Description

The ListOrders operation returns a list of orders created or updated during a time frame that you specify. You define that time frame using the CreatedAfter parameter or the LastUpdatedAfter parameter. You must use one of these parameters, but not both. You can also apply a range of filtering criteria to narrow the list of orders that is returned. The ListOrders operation includes order information for each order returned, including AmazonOrderId, OrderStatus, FulfillmentChannel, and LastUpdateDate.

Availability of buyer contact and charge information

The following tables show when the ListOrders operation returns buyer contact information (BuyerEmail, BuyerName, ShippingAddress) and charge information (OrderTotal).

Table 1. Standard orders
For a standard order with this order status: …the ListOrders operation returns these buyer contact and charge information response elements:
Pending None
Unshipped, PartiallyShipped, Shipped BuyerEmail1, BuyerName, ShippingAddress, OrderTotal
Table 2. Pre-orders
For a pre-order with this order status: …the ListOrders operation returns these buyer contact and charge information response elements:
PendingAvailability2, Pending BuyerEmail1, BuyerName
Unshipped, PartiallyShipped, Shipped BuyerEmail1, BuyerName, ShippingAddress, OrderTotal
  1. BuyerEmail is not returned for Fulfillment by Amazon gift orders.
  2. The PendingAvailability status is available only for pre-orders in Japan.

Availability

This operation is available in all marketplaces.

Throttling

The ListOrders and ListOrdersByNextToken operations together share a maximum request quota of six and a restore rate of one request every minute. For definitions of throttling terminology, see Orders API.

Request parameters

Name Description Required Values
CreatedAfter A date used for selecting orders created after (or at) a specified time. Yes, if LastUpdatedAfter is not specified.

Specifying both CreatedAfter and LastUpdatedAfter returns an error.

Important: Amazon does not guarantee that all orders created after the CreatedAfter date that you specify will be returned. Only orders created after (or on) the specified CreatedAfter date and before (or on) the CreatedBefore date in the response are returned. Always check the CreatedBefore response element to get the exact date range for the orders that are returned.

Example:

You make a call at 2017-02-10T12:10:02, specifying a CreatedAfter date of 2017-02-01T18:12:02, and the CreatedBefore element in the response is 2017-02-10T12:05:02. This means that all of the orders created between 2017-02-01T18:12:02 and 2017-02-10T12:05:02 will be returned. An order that was created on 2017-02-10T12:08:02 will not be returned, even though it was created after 2017-02-01T18:12:02.

In ISO 8601 date time format.

Type: xs:dateTime

CreatedBefore A date used for selecting orders created before (or at) a specified time. No
Important: Amazon does not guarantee that all orders created before the CreatedBefore date that you specify will be returned. Only orders created before (or on) the CreatedBefore date in the response are returned. Always check the CreatedBefore response element to get the exact date range for the orders that are returned.

Example:

You make a call at 2017-02-10T12:10:02, specifying a CreatedBefore date of 2017-02-10T12:10:02, and the CreatedBefore element in the response is 2017-02-10T12:05:02. This means that orders created before (or on) 2017-02-10T12:05:02 will be returned. An order that was created on 2017-02-10T12:08:02 will not be returned, even though it was created before 2017-02-10T12:10:02.

Must be later than CreatedAfter.

In ISO 8601 date time format.

Type: xs:dateTime

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. Yes, if CreatedAfter is not specified.

Specifying both CreatedAfter and LastUpdatedAfter returns an error.

If LastUpdatedAfter is specified, then BuyerEmail and SellerOrderId cannot be specified.

Important: Amazon does not guarantee that all orders updated after the LastUpdatedAfter date that you specify will be returned. Only orders updated after (or on) the specified LastUpdatedAfter date and before (or on) the LastUpdatedBefore date in the response are returned. Always check the LastUpdatedBefore response element to get the exact date range for the orders that are returned.

Example:

You make a call at 2017-02-10T12:10:02, specifying a LastUpdatedAfter date of 2017-02-01T12:10:02, and the LastUpdatedBefore element in the response is 2017-02-10T12:05:02. This means that all of the orders updated between 2017-02-01T12:10:02 and 2017-02-10T12:05:02 will be returned. An order that was updated on 2017-02-10T12:08:02 will not be returned, even though it was updated after 2017-02-01T12:10:02.

In ISO 8601 date time format.

Type: xs:dateTime

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. No
Important: Amazon does not guarantee that all orders updated before the LastUpdatedBefore date that you specify will be returned. Only orders updated before (or on) the LastUpdatedBefore date in the response are returned. Always check the LastUpdatedBefore response element to get the exact date range for the orders that are returned.

Example:

You make a call at 2017-02-10T12:10:02, specifying a LastUpdatedBefore date of 2017-02-10T12:10:02, and the LastUpdatedBefore element in the response is 2017-02-10T12:05:02. This means that orders updated before (or on) 2017-02-10T12:05:02 will be returned. An order that was updated on 2017-02-10T12:08:02 will not be returned, even though it was updated before 2017-02-10T12:10:02.

Must be later than LastUpdatedAfter.

In ISO 8601 date time format.

Type: xs:dateTime

OrderStatus A list of OrderStatus values. Used to select orders with a current status that matches one of the status values that you specify. No OrderStatus 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. The order is not ready for shipment. Note that Preorder is a possible OrderType value in Japan (JP) only.
Pending
The order has been placed but payment has not been authorized. The order is not ready for shipment. Note that for orders with OrderType = Standard, the initial order status is Pending. For orders with OrderType = Preorder (available in JP only), the initial order status is PendingAvailability, and the order passes into the Pending status when the payment authorization process begins.
Unshipped
Payment has been authorized and 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.
Canceled
The order was canceled.
Unfulfillable
The order cannot be fulfilled. This state applies only to Amazon-fulfilled orders that were not placed on Amazon's retail web site.

Unshipped and PartiallyShipped must be used together in this version of the Orders API section. Using one and not the other returns an error.

Default: All

Type: xs:string
MarketplaceId A list of MarketplaceId values. Used to select orders that were placed in the Marketplaces that you specify. Yes Any Marketplace in which the seller is registered to sell.

An error is returned if the value is not a Marketplace in which the seller is registered to sell.

Maximum: 50

Type: xs:string
FulfillmentChannel A list that indicates how an order was fulfilled. No FulfillmentChannel values:
AFN
Fulfilled by Amazon
MFN
Fulfilled by the seller

Default: All

Type: xs:string
PaymentMethod A list of PaymentMethod values. Used to select orders paid for with the payment methods that you specify. No PaymentMethod values:
COD
Cash on delivery
CVS
Convenience store payment
Other
Any payment method other than COD or CVS
Note: COD and CVS values are valid only in Japan (JP).

Default: All

Type: xs:string
BuyerEmail The e-mail address of a buyer. Used to select only the orders that contain the specified e-mail address. No.

If BuyerEmail is specified, then FulfillmentChannel, OrderStatus, PaymentMethod, LastUpdatedAfter, LastUpdatedBefore, and SellerOrderId cannot be specified.

The e-mail address that you provide in your request can be anonymized (by Amazon), or non-anonymized.

Default: All

Type: xs:string

SellerOrderId An order identifier that is specified by the seller. Not an Amazon order identifier. Used to select only the orders that match a seller-specified order identifier. No.

If SellerOrderId is specified, then FulfillmentChannel, OrderStatus, PaymentMethod, LastUpdatedAfter, LastUpdatedBefore, and BuyerEmail cannot be specified.

Default: All

Type: xs:string

MaxResultsPerPage A number that indicates the maximum number of orders that can be returned per page. No Value must be 1 - 100.

Default: 100

Type: xs:positiveInteger

EasyShipShipmentStatus A list of EasyShipShipmentStatus values. Used to select Easy Ship orders with current statuses that match the status values that you specify. If EasyShipShipmentStatus is specified, only Amazon Easy Ship orders are returned.

This parameter is valid only in the India marketplace.

No EasyShipShipmentStatus values:
PendingPickUp
Amazon has not yet picked up the package from the seller.
LabelCanceled
The seller canceled the pickup.
PickedUp
Amazon has picked up the package from the seller.
OutForDelivery
The package is out for delivery.
Damaged
The package was damaged by the carrier.
Delivered
Package has been delivered to the buyer.
RejectedByBuyer
Package has been rejected by the buyer.
Undeliverable
The package cannot be delivered.
ReturnedToSeller
The package was not delivered to the customer and was returned to the seller.
ReturningToSeller
The package was not delivered to the customer and is being returned to the seller.
Lost
Package was lost by the carrier.
Type: xs:string

Response elements

Name Description Required Values
NextToken A generated string used to pass information to your next request. If NextToken is returned, pass the value of NextToken to ListOrdersByNextToken. If NextToken is not returned, there are no more orders to return. No Type: xs:string
LastUpdatedBefore A date returned if you specified LastUpdatedAfter in the request. Only orders updated before (or on) this date are returned. No In ISO 8601 date time format.

Type: xs:dateTime

CreatedBefore A date returned if you specified CreatedAfter in the request. Only orders created before (or on) this date are returned. No In ISO 8601 date time format .

Type: xs:dateTime

Orders A list of orders. No Type: List of Order

Examples

Example query request

For information about standard request requirements, see Required request parameters.

Show example code Hide example code

https://mws.amazonservices.jp/Orders/2013-09-01
  ?AWSAccessKeyId=0PB842EXAMPLE7N4ZTR2
  &Action=ListOrders
  &MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
  &MarketplaceId.Id.1=ATVPDKIKX0DER
  &MarketplaceId.Id.2=A2Q3Y263D00KWC
  &MarketplaceId.Id.3=A1VC38T7YXB528  
  &FulfillmentChannel.Channel.1=MFN
  &PaymentMethod.Method.1=COD
  &PaymentMethod.Method.2=Other
  &OrderStatus.Status.1=Unshipped
  &OrderStatus.Status.2=PendingAvailability
  &SellerId=A2NEXAMPLETF53
  &Signature=ZQLpf8vEXAMPLE0iC265pf18n0%3D
  &SignatureVersion=2
  &SignatureMethod=HmacSHA256
  &LastUpdatedAfter=2017-02-01T18%3A12%3A21
  &Timestamp=2017-02-05T18%3A12%3A21.687Z
  &Version=2013-09-01

↑ Top

Example response

For information about standard response formatting, see Response format.

Show example code Hide example code

<?xml version="1.0"?>
<ListOrdersResponse xmlns="https://mws.amazonservices.com/
    Orders/2013-09-01">
    <ListOrdersResult>
        <NextToken>2YgYW55IGNhcm5hbCBwbGVhc3VyZS4=</NextToken>
        <LastUpdatedBefore>2017-02-25T18%3A10%3A21.687Z</LastUpdatedBefore>
        <Orders>
            <Order>
                <AmazonOrderId>902-3159896-1390916</AmazonOrderId>
                <PurchaseDate>2017-02-20T19:49:35Z</PurchaseDate>
                <LastUpdateDate>2017-02-20T19:49:35Z</LastUpdateDate>
                <OrderStatus>Unshipped</OrderStatus>
                <FulfillmentChannel>MFN</FulfillmentChannel>
                <SalesChannel>Amazon.com</SalesChannel>
                <ShippingAddress>
                    <Name>Buyer name</Name>
                    <AddressLine1>1234 Any St.</AddressLine1>
                    <City>Seattle</City>
                    <StateOrRegion>WA</StateOrRegion>
                    <PostalCode>98103</PostalCode>
                    <CountryCode>US</CountryCode>
                    <AddressType>Commercial</AddressType>
                </ShippingAddress>
                <DefaultShipFromLocationAddress>
                    <Name>Seller name</Name>
                    <AddressLine1>15606 NE Any street</AddressLine1>
                    <AddressLine2>Suite 2</AddressLine2>
                    <City>Redmond</City>
                    <StateOrRegion>WA</StateOrRegion>
                    <PostalCode>98052</PostalCode>
                    <CountryCode>US</CountryCode>
                    <Phone>555 555-5555</Phone>
                    <isAddressSharingConfidential>false</isAddressSharingConfidential>
                </DefaultShipFromLocationAddress>
                <OrderTotal>
                    <CurrencyCode>USD</CurrencyCode>
                    <Amount>25.00</Amount>
                </OrderTotal>
                <NumberOfItemsShipped>0</NumberOfItemsShipped>
                <NumberOfItemsUnshipped>1</NumberOfItemsUnshipped>
                <PaymentMethod>Other</PaymentMethod>
                <PaymentMethodDetails>
                    <PaymentMethodDetail>CreditCard</PaymentMethodDetail>
                </PaymentMethodDetails>
                <MarketplaceId>ATVPDKIKX0DER</MarketplaceId>
                <BuyerEmail>5vlhEXAMPLEh9h5@marketplace.amazon.com</BuyerEmail>
                <BuyerName>Buyer name</BuyerName>
                <BuyerTaxInfo>
                    <CompanyLegalName>Company Name</CompanyLegalName>
                    <TaxingRegion>US</TaxingRegion>
                    <TaxClassifications>
                        <TaxClassification>
                            <Name>VATNumber</Name>
                            <Value>XXX123</Value>
                        </TaxClassification>
                    </TaxClassifications>
                </BuyerTaxInfo>
                <OrderType>StandardOrder</OrderType>
                <EarliestShipDate>2017-02-20T19:51:16Z</EarliestShipDate>
                <LatestShipDate>2017-02-25T19:49:35Z</LatestShipDate>
                <IsBusinessOrder>true</IsBusinessOrder>
                <PurchaseOrderNumber>PO12345678</PurchaseOrderNumber>
                <IsPrime>false</IsPrime>
                <IsPremiumOrder>false</IsPremiumOrder>
                <IsGlobalExpressEnabled>false</IsGlobalExpressEnabled>
            </Order>
            <Order>
                <AmazonOrderId>483-3488972-0896720</AmazonOrderId>
                <PurchaseDate>20178-02-20T19:49:35Z</PurchaseDate>
                <LastUpdateDate>2017-02-20T19:49:35Z</LastUpdateDate>
                <OrderStatus>Unshipped</OrderStatus>
                <FulfillmentChannel>MFN</FulfillmentChannel>
                <ShippingAddress>
                    <Name>Buyer name</Name>
                    <AddressLine1>1234 Avenida Qualquer</AddressLine1>
                    <City>Sao Paulo</City>
                    <PostalCode>08474-130</PostalCode>
                    <CountryCode>BR</CountryCode>
                    <AddressType>Residential</AddressType>
                </ShippingAddress>
                <OrderTotal>
                    <CurrencyCode>BRL</CurrencyCode>
                    <Amount>100.00</Amount>
                </OrderTotal>
                <NumberOfItemsShipped>0</NumberOfItemsShipped>
                <NumberOfItemsUnshipped>1</NumberOfItemsUnshipped>
                <PaymentMethod>Other</PaymentMethod>
                <PaymentMethodDetails>
                    <PaymentMethodDetail>CreditCard</PaymentMethodDetail>
                </PaymentMethodDetails>
                <MarketplaceId>A2Q3Y263D00KWC</MarketplaceId>
                <BuyerEmail>5vlhEXAMPLEh9h5@marketplace.amazon.com.br</BuyerEmail>
                <BuyerName>John Jones</BuyerName>
                <BuyerCounty>Vila Olimpia</BuyerCounty>
                <BuyerTaxInfo>
                    <TaxingRegion>BR</TaxingRegion>
                    <TaxClassifications>
                        <TaxClassification>
                            <Name>CSTNumber</Name>
                            <Value>XXX123</Value>
                        </TaxClassification>
                    </TaxClassifications>
                </BuyerTaxInfo>
                <EarliestShipDate>2017-02-20T19:51:16Z</EarliestShipDate>
                <LatestShipDate>2017-02-25T19:49:35Z</LatestShipDate>
                <IsBusinessOrder>false</IsBusinessOrder>
                <IsPrime>false</IsPrime>
                <IsPremiumOrder>false</IsPremiumOrder>
                <IsGlobalExpressEnabled>false</IsGlobalExpressEnabled>
            </Order>
            <Order>
                <AmazonOrderId>058-1233752-8214740</AmazonOrderId>
                <PurchaseDate>2017-02-05T00%3A06%3A07.000Z</PurchaseDate>
                <LastUpdateDate>2017-02-07T12%3A43%3A16.000Z</LastUpdateDate>
                <OrderStatus>Unshipped</OrderStatus>
                <FulfillmentChannel>MFN</FulfillmentChannel>
                <ShipServiceLevel>Std JP Kanto8</ShipServiceLevel>
                <ShippingAddress>
                    <Name>Jane Smith</Name>
                    <AddressLine1>1-2-10 Akasaka</AddressLine1>
                    <City>Tokyo</City>
                    <PostalCode>107-0053</PostalCode>
                    <CountryCode>JP</CountryCode>                  
                </ShippingAddress>
                <OrderTotal>
                    <CurrencyCode>JPY</CurrencyCode>
                    <Amount>1507.00</Amount>
                </OrderTotal>
                <NumberOfItemsShipped>0</NumberOfItemsShipped>
                <NumberOfItemsUnshipped>1</NumberOfItemsUnshipped>
                <PaymentExecutionDetail>
                    <PaymentExecutionDetailItem>
                        <Payment>
                            <Amount>10.00</Amount>
                            <CurrencyCode>JPY</CurrencyCode>
                        </Payment>
                        <PaymentMethod>PointsAccount</PaymentMethod>
                    </PaymentExecutionDetailItem>
                    <PaymentExecutionDetailItem>
                        <Payment>
                            <Amount>317.00</Amount>
                            <CurrencyCode>JPY</CurrencyCode>
                        </Payment>
                        <PaymentMethod>GC</PaymentMethod>
                    </PaymentExecutionDetailItem>
                    <PaymentExecutionDetailItem>
                        <Payment>
                            <Amount>1180.00</Amount>
                            <CurrencyCode>JPY</CurrencyCode>
                        </Payment>
                        <PaymentMethod>COD</PaymentMethod>
                    </PaymentExecutionDetailItem>
                </PaymentExecutionDetail>
                <PaymentMethod>COD</PaymentMethod>
                <PaymentMethodDetails>
                    <PaymentMethodDetail>COD</PaymentMethodDetail>
                </PaymentMethodDetails>
                <MarketplaceId>A1VC38T7YXB528</MarketplaceId>
                <BuyerEmail>5vlhEXAMPLEh9h5@marketplace.amazon.co.jp</BuyerEmail>
                <BuyerName>Jane Smith</BuyerName>
                <ShipmentServiceLevelCategory>Standard </ShipmentServiceLevelCategory>
                <OrderType>SourcingOnDemandOrder</OrderType>
                <IsBusinessOrder>false</IsBusinessOrder>
                <IsPrime>false</IsPrime>
                <IsPremiumOrder>false</IsPremiumOrder>
                <IsGlobalExpressEnabled>false</IsGlobalExpressEnabled>
                <PromiseResponseDueDate>2017-08-31T23:58:44Z</PromiseResponseDueDate>
                <IsEstimatedShipDateSet>true</IsEstimatedShipDateSet>
            </Order>
        </Orders>
    </ListOrdersResult>
    <ResponseMetadata>
        <RequestId>88faca76-b600-46d2-b53c-0c8c4533e43a</RequestId>
    </ResponseMetadata>
</ListOrdersResponse>

↑ Top