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.
Returns orders created or updated during a time frame that you specify.
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.
The following tables show when the ListOrders operation returns buyer contact information (BuyerEmail, BuyerName, ShippingAddress) and charge information (OrderTotal).
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 |
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 |
This operation is available in all marketplaces.
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.
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. 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. 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. 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. 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:
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:
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:
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:
|
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 |
For information about standard request requirements, see Required request parameters.
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
For information about standard response formatting, see Response format.
<?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>