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

Orders Datatypes

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.

Address

The shipping address for the order.

Operations

The Address datatype is used in a response element of the following operations:

Datatype content

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

AutomatedShippingSettings

The automated shipping settings details, including shipping settings and promises provided by Amazon.

Operations

The AutomatedShippingSettings datatype is used in a response element of the following operations:

Datatype content

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

BuyerCustomizedInfo

Buyer information for custom orders from the Amazon Custom program.

Operations

The BuyerCustomizedInfo datatype is used in a response element of the following operations:

Datatype content

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

BuyerIdentificationInformation

Turkish Citizen ID and legal name. Only returned for international orders to Turkey.

Operations

The BuyerIdentificationInformation datatype is used in a response element of the following operations:

Datatype content

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

BuyerRequestedCancel

Contains information on whether and why the buyer has requested a cancellation.

Operations

The BuyerRequestedCancel datatype is used in a response element of the following operations:

Datatype content

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

BuyerTaxInfo

Tax information about the buyer.

Operations

The BuyerTaxInfo datatype is used in a response element of the following operations:

Datatype content

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.

Money

Currency type and amount.

Operations

The Money datatype is used in a response element of the following operations:

Datatype content

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

Order information.

Operations

The Order datatype is used in a response element of the following operations:

Datatype content

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:
  • COD - Cash On Delivery. Available only in Japan (JP).
  • CVS - Convenience Store. Available only in JP.
  • Other - A payment method other than COD and CVS.
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:

  • StandardOrder - An order that contains items for which you currently have inventory in stock.
  • Preorder - An order that contains items with a release date that is in the future.
  • SourcingOnDemandOrder - A Sourcing On Demand order.
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:

  • true - The order is an Amazon Business order.
  • false - The order is not an Amazon Business order.
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:

  • true - The items in this order were bought and re-sold by ABEU.
  • false - The items in this order were not bought and re-sold by ABEU.
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:

  • true - The items in this order were bought and re-sold by ABEU.
  • false - The items in this order were not bought and re-sold by ABEU.
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:

  • true - The items in this order are marked to be delivered to an Access Point.
  • false - The items in this order are not marked to be delivered to an Access Point.
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

OrderItem information.

Operations

The OrderItem datatype is used in a response element of the following operations:

Datatype content

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:

  • BusinessPrice - A special price that is available only for Amazon Business orders.
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

PaymentExecutionDetailItem

Information about a sub-payment method used to pay for a COD order.

Operations

The PaymentExecutionDetailItem datatype is used in a response element of the following operations:

Datatype content

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:

  • COD - Cash On Delivery. Available only in Japan (JP).
  • GC - Gift Card. Available only in JP.
  • PointsAccount - Amazon Points. Available only in JP.
Yes Type: xs:string

PaymentMethodDetails

A list of payment methods for the order.

Operations

The PaymentMethodDetails datatype is used in a response element of the following operations:

Datatype content

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

ProductInfo

Product information for the item. This datatype is used only in the US, Spain, UK, France, Germany, Italy, India, and Japan marketplaces.

Operations

The ProductInfo datatype is used in a response element of the following operations:

Datatype content

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

PointsGranted

The number and value of Amazon Points granted with the purchase of an item. This datatype is used only in the Japan marketplace.

Operations

The PointsGranted datatype is used in a response element of the following operations:

Datatype content

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

TaxClassification

A tax type and identifier.

Operations

The TaxClassification datatype is used in a response element of the following operations:

Datatype content

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

TaxCollection

Information about withheld taxes.

Operations

The TaxCollection datatype is used in a response element of the following operations:

Datatype content

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

Related topics