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.
The following datatypes are used in the response elements of the Amazon Marketplace Web Service (Amazon MWS) Orders API section:
Datatype | Description |
---|---|
Address | The shipping address for the order. |
AutomatedShippingSettings | The automated shipping settings details, including shipping settings and promises provided by Amazon. |
BuyerCustomizedInfo | Buyer information for custom orders from the Amazon Custom program. |
BuyerIdentificationInformation | Turkish Citizen ID and legal name. Only returned for international orders to Turkey. |
BuyerRequestedCancel | Contains information on whether and why the buyer has requested a cancellation. |
BuyerTaxInfo | Tax information about the buyer. |
Money | Currency type and amount. |
Order | Order information. |
OrderItem | OrderItem information. |
PaymentExecutionDetailItem | Information about a sub-payment method used to pay for a COD order. |
PaymentMethodDetails | A list of payment methods for the order. |
PointsGranted | The number and value of Amazon Points granted with the purchase of an item. This datatype is used only in the Japan marketplace. |
ProductInfo | Product information for the item. This datatype is used only in the US, UK, Germany, and Japan marketplaces. |
TaxClassification | A tax type and identifier. |
TaxCollection | Information about withheld taxes. |
The shipping address for the order.
The following table shows the elements of the Address datatype:
Name | Description | Required | Values |
---|---|---|---|
Name | The name. | Yes | Type: xs:string |
AddressLine1 | The street address. | No | Type: xs:string |
AddressLine2 | Additional street address information, if required. | No | Type: xs:string |
AddressLine3 | Additional street address information, if required. | No | Type: xs:string |
City | The city. | No | Type: xs:string |
Municipality | The municipality. | No | Type: xs:string |
County | The county. | No | Type: xs:string |
District | The district. | No | Type: xs:string |
StateOrRegion | The state or region. | No | Type: xs:string |
PostalCode | The postal code. | No | Type: xs:string |
CountryCode | The country code. | No | A two-character country code, in ISO 3166-1 alpha-2
format. Type: xs:string |
Phone | The phone number. | No. Not returned for Fulfillment by Amazon (FBA) orders. | Type: xs:string |
AddressType | Indicates whether the address is commercial or
residential. This element is used only in the US marketplace. |
No | AddressType values:
Commercial,
Residential Type: xs:string |
The automated shipping settings details, including shipping settings and promises provided by Amazon.
The following table shows the elements of the AutomatedShippingSettings datatype:
Name | Description | Required | Values |
---|---|---|---|
hasAutomatedShippingSettings | true if the order has automated shipping settings generated by Amazon. | Yes | Type: xs:boolean |
automatedCarrier | The auto-generated carrier for orders with automated shipping settings. | No | Type: xs:string |
automatedShipMethod | The auto-generated shipping service for orders with automated shipping settings. | No | Type: xs:string |
Buyer information for custom orders from the Amazon Custom program.
The following table shows the elements of the BuyerCustomizedInfo datatype:
Name | Description | Required | Values |
---|---|---|---|
CustomizedURL | The location of a zip file containing Amazon Custom data. | Yes | Type: xs:string |
Turkish Citizen ID and legal name. Only returned for international orders to Turkey.
The following table shows the elements of the BuyerIdentificationInformation datatype:
Name | Description | Required | Values |
---|---|---|---|
BuyerCitizenId | The Turkish Citizen ID of the buyer. | Yes | Type: xs:string |
BuyerLegalName | The legal name of the buyer. | Yes | Type: xs:string |
Contains information on whether and why the buyer has requested a cancellation.
The following table shows the elements of the BuyerRequestedCancel datatype:
Name | Description | Required | Values |
---|---|---|---|
IsBuyerRequestedCancel | true if the buyer has requested a cancellation. | Yes | Type: xs:boolean |
BuyerCancelReason | The reason for the requested cancellation. | Yes | Type: xs:string |
Tax information about the buyer.
The following table shows the elements of the BuyerTaxInfo datatype:
Name | Description | Required | Values |
---|---|---|---|
CompanyLegalName | The legal name of the company. | No | Type: xs:string |
TaxingRegion | The country or region imposing the tax. | No | Type: xs:string |
TaxClassifications | A list of tax classifications. | No | Type: List of TaxClassification. At least one TaxClassification response element is required. |
Currency type and amount.
The following table shows the elements of the Money datatype:
Name | Description | Required | Values |
---|---|---|---|
CurrencyCode | Three-digit currency code. In ISO 4217 format . | No | Type: xs:string |
Amount | The currency amount. | No | Type: xs:string |
Order information.
The following table shows the elements of the Order datatype:
Name | Description | Required | Values |
---|---|---|---|
AmazonOrderId | An Amazon-defined order identifier, in 3-7-7 format.
|
Yes | Type: xs:string |
SellerOrderId | A seller-defined order identifier. | No | Type: xs:string |
PurchaseDate | The date when the order was created. | Yes | Type: xs:dateTime |
LastUpdateDate | The date when the order was last
updated. Note: LastUpdateDate is
returned with an incorrect date for orders that were
last updated before 2009-04-01.
|
Yes | Date values in ISO 8601 date time format. Type: xs:dateTime |
OrderStatus | The current order status. | Yes | Type: xs:string |
FulfillmentChannel | How the order was fulfilled: by Amazon (AFN) or by the seller (MFN). | No | Type: xs:string |
SalesChannel | The sales channel of the first item in the order. | No | Type: xs:string |
OrderChannel | The order channel of the first item in the order. | No | Type: xs:string |
ShipServiceLevel | The shipment service level of the order. | No | Type: xs:string |
ShippingAddress | The shipping address for the order. | No | Type: Address |
DefaultShipFromLocationAddress | The seller's default shipping address in their Seller Central account. Amazon assigns this address to the order before shipment confirmation. | No | Type: Address |
OrderTotal | The total charge for the order. | No | Type: Money |
NumberOfItemsShipped | The number of items shipped. | No | Type: xs:int |
NumberOfItemsUnshipped | The number of items unshipped. | No | Type: xs:int |
PaymentExecutionDetail | Information about sub-payment methods for a Cash On
Delivery (COD) order. A COD order is an order with
PaymentMethod =
COD. Contains one or more
PaymentExecutionDetailItem response
elements. Note: For a
COD order that is paid for using one sub-payment method,
one PaymentExecutionDetailItem
response element is returned, with
PaymentExecutionDetailItem/PaymentMethod
= COD. For a COD order that is paid
for using multiple sub-payment methods, two or more
PaymentExecutionDetailItem
response elements are returned.
|
No. Returned only for COD orders. Available only in Japan (JP). | Type: List of PaymentExecutionDetailItem |
PaymentMethod | The payment method for the order. This response element is limited to Cash On Delivery (COD) and Convenience Store (CVS) payment methods. Unless you need the specific COD payment information provided by the PaymentExecutionDetailItem element, we recommend using the PaymentMethodDetails response element to get payment method information. | No | PaymentMethod values:
Note: Orders with
PaymentMethod =
COD can be paid for using
multiple sub-payment methods. Each sub-payment method is
represented by a
PaymentExecutionDetailItem
object.
Type: xs:string |
PaymentMethodDetails | A list of payment methods for the order. | No | Type: PaymentMethodDetails |
IsReplacementOrder | true if this is a replacement
order.
|
No | Type: xs:boolean |
ReplacedOrderId | The AmazonOrderId value for the
order that is being replaced.
|
No. Returned only if IsReplacementOrder = true | Type: xs:string |
MarketplaceId | The anonymized identifier for the
Marketplace where the order was placed.
|
No | Type: xs:string |
BuyerEmail | The anonymized e-mail address of the buyer. | No | Type: xs:string |
BuyerName | The name of the buyer. | No | Type: xs:string |
BuyerCounty | The county of the buyer. | No. This element is used only in the Brazil marketplace. | Type: xs:string |
BuyerTaxInfo | Tax information about the buyer. | No | Type: BuyerTaxInfo |
ShipmentServiceLevelCategory | The shipment service level category of the
order. ShipmentServiceLevelCategory values: Expedited, FreeEconomy, NextDay, SameDay, SecondDay, Scheduled, Standard |
No | Type: xs:string |
EasyShipShipmentStatus | The status of the Amazon Easy Ship
order. This element is included only for Amazon Easy Ship
orders. EasyShipShipmentStatus values: PendingPickUp, LabelCanceled, PickedUp, OutForDelivery, Damaged, Delivered, RejectedByBuyer, Undeliverable, ReturnedToSeller, ReturningToSeller Amazon Easy Ship is available only in the India marketplace. |
No | Type: xs:string |
OrderType | The type of the order. OrderType values:
Note: Preorder and
SourcingOnDemandOrder are
possible OrderType values only in
the Japan marketplace.
|
No | Type: xs:string |
EarliestShipDate | The start of the time period that you have committed to
ship the order. In ISO 8601 date time format. Note: EarliestShipDate might not be
returned for orders placed before February 1,
2013.
|
No. Returned only for seller-fulfilled orders. | Type: xs:dateTime |
LatestShipDate | The end of the time period that you have committed to
ship the order. In ISO 8601 date time format. Note: LatestShipDate might
not be returned for orders placed before February 1,
2013.
|
No. Returned only for seller-fulfilled orders. | Type: xs:dateTime |
EarliestDeliveryDate | The start of the time period that you have commited to fulfill the order. In ISO 8601 date time format. | No. Returned only for seller-fulfilled orders that do not have a PendingAvailability, Pending, or Canceled status. | Type: xs:dateTime |
LatestDeliveryDate | The end of the time period that you have commited to fulfill the order. In ISO 8601 date time format. | No. Returned only for seller-fulfilled orders that do not have a PendingAvailability, Pending, or Canceled status. | Type: xs:dateTime |
IsBusinessOrder | true if the order is an Amazon
Business order. An Amazon Business order is an order where
the buyer is a Verified Business
Buyer. IsBusinessOrder values:
|
No | Type: xs:boolean |
IsSoldByAB | true if the items in this order were
bought and re-sold by Amazon Business EU SARL
(ABEU). IsSoldByAB values:
|
No | Type: xs:boolean |
IsIBA | true if the items in this order were
bought and re-sold by Amazon Business EU SARL
(ABEU). IsIBA values:
|
No | Type: xs:boolean |
IsAccessPointOrder | true if this order is marked to be delivered to an Access Point.
The access location is chosen by the customer. Access Points include Amazon Hub Lockers,
Amazon Hub Counters, and pickup points operated by carriers.
IsAccessPointOrder values:
|
No | Type: xs:boolean |
PurchaseOrderNumber | The purchase order (PO) number entered by the buyer at checkout. | No. Returned only for orders where the buyer entered a PO number at checkout. | Type: xs:string |
IsPrime | true if the order is a seller-fulfilled Amazon Prime order. | No | Type: xs:boolean |
IsPremiumOrder | true if the order has a Premium Shipping Service Level Agreement. For more information about Premium Shipping orders, see "Premium Shipping Options" in the Seller Central Help. | No | Type: xs:boolean |
IsGlobalExpressEnabled | true if the order is a Global Express order. For more information about the Global Express program, see "Global Express" in the Seller Central Help. | No | Type: xs:boolean |
PromiseResponseDueDate | Indicates the date by which the seller must respond to the buyer with an Estimated Ship Date. | No. Returned only for Sourcing on Demand orders. | Type: xs:dateTime |
IsEstimatedShipDateSet | true if the Estimated Ship Date is set for the order. | No. Returned only for Sourcing on Demand orders. | Type: xs:boolean |
AutomatedShippingSettings | The automated shipping settings details, including shipping settings and promises provided by Amazon. | No | Type: AutomatedShippingSettings |
OrderItem information.
The following table shows the elements of the OrderItem datatype:
Name | Description | Required | Values |
---|---|---|---|
ASIN | The Amazon Standard Identification Number (ASIN) of the item. | Yes | Type: xs:string |
OrderItemId | An Amazon-defined order item identifier. | Yes | Type: xs:string |
SellerSKU | The seller SKU of the item. | No | Type: xs:string |
BuyerCustomizedInfo | Buyer information for custom orders from the Amazon Custom program. | No | Type: BuyerCustomizedInfo |
BuyerRequestedCancel | Contains information on whether and why the buyer has requested a cancellation. | No | Type: BuyerRequestedCancel |
Title | The name of the item. | No | Type: xs:string |
QuantityOrdered | The number of items in the order. | Yes | Type: xs:int |
QuantityShipped | The number of items shipped. | No | Type: xs:int |
PointsGranted | The number and value of Amazon Points granted with the
purchase of an item. Note: PointsGranted is a
response element only in Japan (JP).
|
No. Returned only if Amazon Points were granted with the purchase of an item. For more information about the Amazon Points program in Japan, see the Seller Central Help (JP). | Type: PointsGranted |
ProductInfo | Product information for the item. | No | Type: ProductInfo |
ItemPrice | The selling price of the order item. Note that an order item is an item and a quantity. This means that the value of ItemPrice is equal to the selling price of the item multiplied by the quantity ordered. Note that ItemPrice excludes ShippingPrice and GiftWrapPrice. For a more detailed explanation of an order item, see Orders API. | No | Type: Money |
ShippingPrice | The shipping price of the item. | No | Type: Money |
GiftWrapPrice | The gift wrap price of the item. | No | Type: Money |
TaxCollection | Information about withheld taxes. | No | Type: TaxCollection |
ItemTax | The tax on the item price. | No | Type: Money |
ShippingTax | The tax on the shipping price. | No | Type: Money |
GiftWrapTax | The tax on the gift wrap price. | No | Type: Money |
ShippingDiscount | The discount on the shipping price. | No | Type: Money |
ShippingDiscountTax | The tax on the discount on the shipping price. | No | Type: Money |
PromotionDiscount | The total of all promotional discounts in the offer. | No | Type: Money |
PromotionDiscountTax | The tax on the total of all promotional discounts in the offer. | No | Type: Money |
PromotionIds | A list of PromotionId elements. | No | Type: List of xs:string |
CODFee | The fee charged for COD
service. Note: CODFee is a
response element only in Japan (JP).
|
No | Type: Money |
CODFeeDiscount | The discount on the COD fee.
Note: CODFeeDiscount is a
response element only in Japan (JP).
|
No | Type: Money |
IsGift | true if the item is a gift. | No | Type: xs:boolean |
GiftMessageText | A gift message provided by the buyer. | No | Type: xs:string |
GiftWrapLevel | The gift wrap level specified by the buyer. | No | Type: xs:string |
ConditionNote | The condition of the item as described by the seller. | No | Type: xs:string |
ConditionId | The condition of the item.
ConditionId values: New, Used, Collectible, Refurbished, Preorder, Club. |
No | Type: xs:string |
ConditionSubtypeId | The subcondition of the item.
ConditionSubtypeId values: New, Mint, Very Good, Good, Acceptable, Poor, Club, OEM, Warranty, Refurbished Warranty, Refurbished, Open Box, Any, Other |
No | Type: xs:string |
ScheduledDeliveryStartDate | The start date of the scheduled delivery window in the
time zone of the order destination. In ISO 8601 date time format. Note: Scheduled
delivery is available only in Japan (JP).
|
No. Only returned if the order is a scheduled delivery. | Type: xs:string |
ScheduledDeliveryEndDate | The end date of the scheduled delivery window in the time
zone of the order destination. In ISO 8601 date time format. Note: Scheduled
delivery is available only in Japan (JP).
|
No. Only returned if the order is a scheduled delivery. | Type: xs:string |
PriceDesignation | Indicates that the selling price is a special price that
is available only for Amazon Business orders. For more
information about the Amazon Business Seller Program, see
the Amazon Business website. PriceDesignation values:
|
No. Returned only for order items from orders with IsBusinessOrder = true. | Type: xs:string |
IsTransparency | true if Transparency codes are required. | No | Type: xs:boolean |
SerialNumberRequired | true if the product type for this item has a serial number. | No. Returned only for Amazon Easy Ship orders. | Type: xs:boolean |
IossNumber | The IOSS number for the marketplace. Sellers shipping to the European Union (EU) from outside of the EU must provide this IOSS number to their carrier when Amazon has collected the VAT on the sale. | No | Type: xs:string |
Information about a sub-payment method used to pay for a COD order.
The following table shows the elements of the PaymentExecutionDetailItem datatype:
Name | Description | Required | Values |
---|---|---|---|
Payment | The amount paid using the sub-payment method indicated by the sibling PaymentMethod response element. | Yes | Type: Money |
PaymentMethod | A sub-payment method for a COD
order. PaymentMethod values:
|
Yes | Type: xs:string |
A list of payment methods for the order.
The following table shows the elements of the PaymentMethodDetails datatype:
Name | Description | Required | Values |
---|---|---|---|
PaymentMethodDetail | A payment method for the order. For example, GiftCertificate or CreditCard. | No | Type: xs:string |
Product information for the item. This datatype is used only in the US, Spain, UK, France, Germany, Italy, India, and Japan marketplaces.
The following table shows the elements of the ProductInfo datatype:
Name | Description | Required | Values |
---|---|---|---|
NumberOfItems | The total number of items that are included in the ASIN. | No | Type: xs:int |
The number and value of Amazon Points granted with the purchase of an item. This datatype is used only in the Japan marketplace.
The following table shows the elements of the PointsGranted datatype:
Name | Description | Required | Values |
---|---|---|---|
PointsNumber | The number of Amazon Points granted with the purchase of an item. | No | Type: xs:int |
PointsMonetaryValue | The monetary value of the Amazon Points granted. | No | Type: Money |
A tax type and identifier.
The following table shows the elements of the TaxClassification datatype:
Name | Description | Required | Values |
---|---|---|---|
Name | The type of tax. | Yes | Type: xs:string |
Value | The buyer's tax identifier. | Yes | Type: xs:string |
Information about withheld taxes.
The following table shows the elements of the TaxCollection datatype:
Name | Description | Required | Values |
---|---|---|---|
Model | The tax collection model applied to the item. | Yes | Model value:
MarketplaceFacilitator - Tax is
withheld and remitted to the taxing authority by Amazon on
behalf of the seller. Type: xs:string |
ResponsibleParty | The party responsible for withholding the taxes and remitting them to the taxing authority. | Yes | ResponsibleParty value:
Amazon Services, Inc. Type: xs:string |