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

Merchant Fulfillment Datatypes

The following datatypes are used in the Amazon Marketplace Web Service (Amazon MWS) Merchant Fulfillment service:

Datatype Description
AdditionalInputs Contains the SellerInputDefinition element (a map of additional seller inputs) and the AdditionalInputFieldName element (the key to the map).
Address Postal address information.
CurrencyAmount Currency type and amount.
FileContents Document data and checksum.
HazmatType Hazardous materials options for a package.
Item An Amazon order item identifier and a quantity.
ItemLevelFieldsList A list of additional seller inputs (at the item level), returned by the GetAdditionalSellerInputs operation.
ItemLevelSellerInputsList A list of additional seller inputs (at the item level), used as input to the CreateShipment operation.
Label Data for creating a shipping label and dimensions for printing the label.
LabelCustomization Custom text for shipping labels.
LabelDimensions Dimensions for printing a shipping label.
PackageDimensions The dimensions of a package contained in a shipment.
RejectedShippingService A shipping service that is ineligible based on the specified ShipmentRequestDetails information.
SellerInputDefinition Defines the additional seller input that is required from the seller.
Shipment The details of a shipment, including the shipment status.
ShipmentLevelFields A list of additional seller inputs (at the shipment level), used as input to the CreateShipment operation.
ShipmentLevelSellerInputsList A list of additional seller inputs (at the shipment level), used as input to the CreateShipment operation.
ShipmentRequestDetails Shipment information required for requesting shipping service offers or for creating a shipment.
ShippingOfferingFilter Specifies particular requirements for eligible shipping service offers.
ShippingService A shipping service offer made by a carrier.
ShippingServiceOptions Extra services provided by a carrier.
TemporarilyUnavailableCarrier A carrier who is temporarily unavailable, most likely due to a service outage experienced by the carrier.
TermsAndConditionsNotAcceptedCarrier A carrier whose terms and conditions have not been accepted by the seller.
TransparencyCodeList List of Transparency codes.
Weight The weight value and unit of measurement.

AdditionalInputs

Contains the SellerInputDefinition element (a map of additional seller inputs) and the AdditionalInputFieldName element (the key to the map).

AdditionalInputs elements

Name Description Required Values
AdditionalInputFieldName The name of the additional seller input. Get this value from a ShipmentLevelFields response member returned by the GetAdditionalSellerInputs operation. Yes Example values: NON_DELIVERABLE_INSTRUCTIONS, SENDER_ADDRESS_TRANSLATED

Type: xs:string

SellerInputDefinition Defines the additional seller input that is required from the seller. Yes Type: SellerInputDefinition

Address

Postal address information.

Address elements

Name Description Required Values
Name The name or business name. Yes Maximum: 30 characters.

Type: xs:string

AddressLine1 The street address information. Yes Maximum: 180 characters.

Type: xs:string

AddressLine2 Additional street address information. No Maximum: 60 characters.

Type: xs:string

AddressLine3 Additional street address information. No Maximum: 60 characters.

Type: xs:string

DistrictOrCounty The district or county. No Maximum: 30 characters.

Type: xs:string

Email The email address. Yes Maximum: 256 characters.

Type: xs:string

City The city. Yes Maximum: 30 characters.

Type: xs:string

StateOrProvinceCode The state or province code. No. Required in the Canada, US, and UK marketplaces. Also required for shipments originating from China. Maximum: 30 characters.

Type: xs:string

PostalCode The zip code or postal code. Yes Maximum: 30 characters.

Type: xs:string

CountryCode The country code. Yes A two-character country code, in ISO 3166-1 alpha-2 format.

Type: xs:string

Phone The phone number. Yes Maximum: 30 characters.

Type: xs:string

CurrencyAmount

Currency type and amount.

CurrencyAmount elements

Name Description Required Values
CurrencyCode Three-digit currency code. Yes In ISO 4217 format .

Type: xs:string

Amount The currency amount. Yes Type: xs:decimal

FileContents

Document data and checksum.

FileContents elements

Name Description Required Values
Contents Data for printing labels, in the form of a Base64-encoded, GZip-compressed string. Yes Type: xs:string
FileType The file type for a label. Yes Type: xs:string
Valid values:
  • application/pdf
  • application/zpl
  • image/png
Checksum An MD5 hash to validate the PDF document data, in the form of a Base64-encoded string. Yes Type: xs:string

HazmatType

Hazardous materials options for a package. Consult the terms and conditions for each carrier for more information on hazardous materials.

HazmatType enumeration

Name Description
None This package does not contain hazardous material.
LQHazmat This package contains limited quantities of hazardous material.

Item

An Amazon order item identifier and a quantity.

Item elements

Name Description Required Values
OrderItemId An Amazon-defined identifier for an individual item in an order. Used in the XML response to an order query request (Order API/Order XML). Yes Type: xs:string
Quantity The number of items. Yes Type: xs:int
ItemWeight The weight of the item. No Type: Weight
ItemDescription The description of the item. No Type: xs:string
TransparencyCodeList List of Transparency codes. No Type: TransparencyCodeList
ItemLevelSellerInputsList A list of additional seller inputs (at the item level), used as input to the CreateShipment operation. No Type: ItemLevelSellerInputsList

ItemLevelFieldsList

A list of additional seller inputs (at the item level), returned by the GetAdditionalSellerInputs operation.

ItemLevelFieldsList elements

Name Description Required Values
Asin The ASIN of the item for which you are getting additional seller inputs. Yes Type: xs:string
AdditionalInputs Contains the SellerInputDefinition element (a map of additional seller inputs) and the AdditionalInputFieldName element (the key to the map). Yes Type: AdditionalInputs

ItemLevelSellerInputsList

A list of additional seller inputs (at the item level), used as input to the CreateShipment operation.

ItemLevelSellerInputsList elements

Name Description Required Values
AdditionalSellerInputs Contains additional seller input information. Yes AdditionalSellerInputs contains these elements:
  • AdditionalInputFieldName - The name of the additional seller input. Example values: HS_CODE. Get this value from an AdditionalInputs response member returned by the GetAdditionalSellerInputs operation.
  • AdditionalSellerInput - Additional seller input information. AdditionalSellerInput contains these elements:
    • DataType - The type of the additional seller input. Values: String, Boolean, Integer, Timestamp, Address, Weight, Dimension, Currency. Get the DataType value from an SellerInputDefinition element returned by the GetAdditionalSellerInputs operation.
    • ValueAs[DataType] (where [DataType] matches the value of the DataType element) - The value of the additional seller input. For syntax requirements, see the Constraints element that is associated with this ValueAs[DataType]. Example values: ValueAsString (Type: xs:string), ValueAsCurrency (Type: CurrencyAmount), ValueAsWeight (Type: Weight). Get these values from the seller.

Label

Data for creating a shipping label and dimensions for printing the label.

Label elements

Name Description Required Values
CustomTextForLabel Custom text to print on the label.
Note: Custom text is only included on labels that are in ZPL format (ZPL203). FedEx does not support CustomTextForLabel.
No Maximum: 14 characters

Type: xs:string

Dimensions Dimensions for printing a shipping label. Yes Type: LabelDimensions
FileContents Document data and checksum. Yes Type: FileContents
LabelFormat The label format. No Must match one of the AvailableLabelFormats returned by GetEligibleShippingServices.

Type: xs:string

StandardIdForLabel The type of standard identifier to print on the label. No StandardIdForLabel values: AmazonOrderId.

Type: xs:string

LabelCustomization

Custom text for shipping labels.

Label elements

Name Description Required Values
CustomTextForLabel Custom text to print on the label.
Note: Custom text is only included on labels that are in ZPL format (ZPL203). FedEx does not support CustomTextForLabel.
No Maximum: 14 characters

Type: xs:string

StandardIdForLabel The type of standard identifier to print on the label. No StandardIdForLabel values: AmazonOrderId.

Type: xs:string

LabelDimensions

Dimensions for printing a shipping label.

LabelDimensions elements

Name Description Required Values
Length The length dimension. Yes A decimal greater than zero.

Type: xs:decimal

Width The width dimension. Yes A decimal greater than zero.

Type: xs:decimal

Unit The unit of measurement. Yes Unit values: inches or centimeters

Type: xs:string

PackageDimensions

The dimensions of a package contained in a shipment.

PackageDimensions elements

Name Description Required Values
Length The length dimension. No. If you don't specify the PredefinedPackageDimensions request parameter, you must specify the Length request parameter. A decimal greater than zero.

Type: xs:decimal

Width The width dimension. No. If you don't specify the PredefinedPackageDimensions request parameter, you must specify the Width request parameter. A decimal greater than zero.

Type: xs:decimal

Height The height dimension. No. If you don't specify the PredefinedPackageDimensions request parameter, you must specify the Height request parameter. A decimal greater than zero.

Type: xs:decimal

Unit The unit of measurement. No. If you don't specify the PredefinedPackageDimensions request parameter, you must specify the Unit request parameter. Unit values: inches or centimeters

Type: xs:string

PredefinedPackageDimensions A parcel token that specifies pre-defined package dimensions. No For PredefinedPackageDimensions values, see the PredefinedPackageDimensions enumeration table.

Type: xs:string

RejectedShippingService

A shipping service that is ineligible based on the specified ShipmentRequestDetails information.

RejectedShippingService elements

Name Description Required Values
CarrierName The name of the carrier. Yes Type: xs:string
ShippingServiceId An Amazon-defined shipping service identifier. For definitions, see Terminology. Yes Type: xs:string
RejectionReasonCode An Amazon-defined reason code for why the shipping service is ineligible. Yes Examples: INELIGIBLE, SHIP_DATE_OUT_OF_RANGE, CARRIER_CANNOT_SHIP_TO_POBOX

Type: xs:string

RejectionReasonMessage A message that explains why the shipping service is ineligible. Yes Example: This ship method is not eligible for this order.

Type: xs:string

ShippingServiceName The name of the carrier's shipping service. Yes Example: UPS Ground.

Type: xs:string

SellerInputDefinition

Defines the additional seller input that is required from the seller.

SellerInputDefinition elements

Name Description Required Values
IsRequired True if this additional seller input is required when creating a shipment. Yes Type: xs:boolean
DataType The type of the additional seller input. Yes DataType values: String, Boolean, Integer, Timestamp, Address, Weight, Dimension, Currency.

Type: xs:string

Constraints Indicates the syntax requirements for the additional seller input. Yes Constraints elements:
  • ValidationRegEx
  • ValidationString
InputDisplayText A label for the additional seller input. Yes Type: xs:string
InputTarget Indicates whether the additional seller input is at the item or shipment level. No InputTarget values: ITEM_LEVEL, SHIPMENT_LEVEL.

Type: xs:string

StoredValue Values stored by Amazon that you previously provided. Yes StoredValue elements:
  • DataType
  • ValueAsString
  • ValueAsBoolean
  • ValueAsInteger
  • ValueAsTimestamp
  • ValueAsAddress
  • ValueAsWeight
  • ValueAsDimension
  • ValueAsCurrency
RestrictedSetValues A set of fixed values for an additional seller input. No Type: xs:string

Shipment

The details of a shipment, including the shipment status.

Shipment elements

Name Description Required Values
ShipmentId An Amazon-defined shipment identifier. Yes Type: xs:string
AmazonOrderId An Amazon-defined order identifier in 3-7-7 format. Yes Maximum: 50 characters.

Type: xs:string

SellerOrderId A seller-defined order identifier. No Maximum: 64 characters.

Type: xs:string

ItemList A list of items to be included in a shipment. Yes Type: List of Item
ShipFromAddress The address from which the shipment ships. Yes Type: Address
ShipToAddress The destination address of the shipment. Yes Type: Address
PackageDimensions The package dimensions. Yes Type: PackageDimensions
Weight The package weight. Yes Type: Weight
Insurance If DeclaredValue was specified with a previous call to the CreateShipment operation, then Insurance indicates the amount that the carrier will insure the shipment for.

If DeclaredValue was not specified with a previous call to the CreateShipment operation, then the shipment will be insured for the carrier's minimum insurance amount, or the combined sale prices that the items in the shipment are listed for, whichever is less.

For information about optional insurance coverage, see the Seller Central Help (UK) (US).

Yes The DeclaredValue value specified in a previous call to the CreateShipment operation. If DeclaredValue was not specified, then the value is zero.

Type: CurrencyAmount

ShippingService The shipping service offer for this shipment. Yes Type: ShippingService
Label Data for creating a shipping label and dimensions for printing the label. If the shipment is canceled, an empty Label element is returned. Yes Type: Label
Status The shipment status. Yes Status values: Purchased, RefundPending, RefundRejected, or RefundApplied. See Status Values table for details.

Type: List of xs:string

TrackingId The shipment tracking identifier provided by the carrier. No Maximum: 30 characters

Type: xs:string

CreatedDate The date that the shipment was created, in ISO 8601 date time format. Yes Type: xs:dateTime
LastUpdatedDate The date that the shipment status last changed, in ISO 8601 date time format. No Type: xs:dateTime

Status Values

Status is a list of strings with the following values.
Name Description
Purchased The seller purchased a label by calling the CreateShipment operation.
RefundPending The seller requested a label refund by calling the CancelShipment operation, and the refund request is being processed by the carrier.
Note:
  • A seller can create a new shipment for an order while Status=RefundPending for a canceled shipment.
  • After a label refund is requested by calling the CancelShipment operation, the order status of the order remains "Shipped".
RefundRejected The label refund request was rejected by the carrier. A refund request is rejected for either of the following reasons:
  • The cancellation window has expired. Cancellation policies vary by carrier. For more information about carrier cancellation policies, see the Seller Central Help..
  • The carrier has already accepted the shipment for delivery.
RefundApplied The refund has been approved and credited to the seller's account.

ShipmentLevelFields

A list of additional seller inputs (at the shipment level), used as input to the CreateShipment operation.

ShipmentLevelFields elements

Name Description Required Values
AdditionalInputFieldName The name of the additional seller input. No AdditionalInputFieldName values:
  • NON_DELIVERABLE_INSTRUCTIONS
  • SENDER_ADDRESS_TRANSLATED
SellerInputDefinition Defines the additional seller input that is required from the seller. No Type: SellerInputDefinition

ShipmentLevelSellerInputsList

A list of additional seller inputs (at the shipment level), used as input to the CreateShipment operation.

ShipmentLevelSellerInputsList elements

Name Description Required Values
AdditionalSellerInputs Contains additional seller input information. Yes AdditionalSellerInputs contains these elements:
  • AdditionalInputFieldName - The name of the additional seller input. Example values: NON_DELIVERABLE_INSTRUCTIONS, SENDER_ADDRESS_TRANSLATED. Get this value from a ShipmentLevelFields response member returned by the GetAdditionalSellerInputs operation.
  • AdditionalSellerInput - Additional seller input information. AdditionalSellerInput contains these elements:
    • DataType - The type of the additional seller input. Values: String, Address. Get the DataType value from an SellerInputDefinition element returned by the GetAdditionalSellerInputs operation.
    • ValueAs[DataType] (where [DataType] matches the value of the DataType element) - The value of the additional seller input. For syntax requirements, see the Constraints element that is associated with this ValueAs[DataType]. Example values: ValueAsString (Type: xs:string), ValueAsAddress (Type: Address). Get these values from the seller.

ShipmentRequestDetails

Shipment information required for requesting shipping service offers or for creating a shipment.

ShipmentRequestDetails elements

Name Description Required Values
AmazonOrderId An Amazon-defined order identifier in 3-7-7 format. Yes Maximum: 50 characters.

Type: xs:string

SellerOrderId A seller-defined order identifier. No Maximum: 64 characters.

Type: xs:string

ItemList A list of items to be included in a shipment. Yes Type: List of Item
ShipFromAddress The address from which the shipment ships. Yes Type: Address
PackageDimensions The package dimensions. Yes Type: PackageDimensions
Weight The package weight. Yes Type: Weight
MustArriveByDate The date by which the package must arrive to keep the promise to the customer, in ISO 8601 date time format.

If MustArriveByDate is specified, only shipping service offers that can be delivered by that date are returned.

No Type: xs:dateTime
ShipDate When used in a request, this is the date that the seller wants to ship the package. When used in a response, this is the date that the package can be shipped by the indicated method. No Type: xs:dateTime
ShippingServiceOptions Extra services offered by the carrier. Yes Type: ShippingServiceOptions
LabelCustomization Label customization options. No Type: LabelCustomization

ShippingOfferingFilter

Specifies particular requirements for eligible shipping service offers.

ShippingOfferingFilter elements

Name Description Required Values
IncludeComplexShippingOptions True if you want to include shipping service offers that require additional seller inputs. No Type: xs:boolean

ShippingService

A shipping service offer made by a carrier.

ShippingService elements

Name Description Required Values
ShippingServiceName A plain text representation of a carrier's shipping service. For example, "UPS Ground" or "FedEx Standard Overnight". Yes Type: xs:string
CarrierName The name of the carrier. Yes Type: xs:string
ShippingServiceId An Amazon-defined shipping service identifier. For definitions, see Terminology. Yes Type: xs:string
ShippingServiceOfferId An Amazon-defined shipping service offer identifier. For definitions, see Terminology. Yes Type: xs:string
ShipDate The date that the carrier will ship the package. Yes Type: xs:dateTime
EarliestEstimatedDeliveryDate The earliest date by which the shipment will be delivered. No Type: xs:dateTime
LatestEstimatedDeliveryDate The latest date by which the shipment will be delivered. No Type: xs:dateTime
Rate The amount that the carrier will charge for the shipment. Yes Type: CurrencyAmount
ShippingServiceOptions Extra services offered by the carrier. Yes Type: ShippingServiceOptions
AvailableLabelFormats The available label formats for a carrier. No May include PNG, PDF, and ZPL203.

Type: List of xs:string

RequiresAdditionalSellerInputs True if this shipping service requires additional seller inputs. Yes Type: xs:boolean

ShippingServiceOptions

Extra services provided by a carrier.

ShippingServiceOptions elements

Name Description Required Values
DeliveryExperience The delivery confirmation level. Yes DeliveryExperience values:
  • DeliveryConfirmationWithAdultSignature - Delivery confirmation with adult signature.
  • DeliveryConfirmationWithSignature - Delivery confirmation with signature. Required for DPD (UK).
  • DeliveryConfirmationWithoutSignature - Delivery confirmation without signature.
  • NoTracking - No delivery confirmation.

Type: xs:string

DeclaredValue The declared value of the shipment. The carrier uses this value to determine how much to insure the shipment for. If DeclaredValue is greater than the carrier's minimum insurance amount, the seller is charged for the additional insurance as determined by the carrier. For information about optional insurance coverage, see the Seller Central Help (UK) (US). No Default: 0

Type: CurrencyAmount

CarrierWillPickUp Indicates whether the carrier will pick up the package.
Note: Scheduled carrier pickup is available only using Dynamex (US), DPD (UK), and Royal Mail (UK).
Yes true if the carrier will pick up the package, otherwise false.

Type: xs:boolean

LabelFormat The seller's preferred label format.
Note: Not all LabelFormat values are supported by all carriers. Specifying a LabelFormat value that is not supported by a carrier will filter out shipping service offers from that carrier.
No Must match one of the AvailableLabelFormats returned by GetEligibleShippingServices.

Type: xs:string

TemporarilyUnavailableCarrier

A carrier who is temporarily unavailable, most likely due to a service outage experienced by the carrier.

TemporarilyUnavailableCarrier elements

Name Description Required Values
CarrierName The name of the carrier. Yes Type: xs:string

TermsAndConditionsNotAcceptedCarrier

A carrier whose terms and conditions have not been accepted by the seller.

TermsAndConditionsNotAcceptedCarrier elements

Name Description Required Values
CarrierName The name of the carrier. Yes Type: xs:string

TransparencyCodeList

List of Transparency codes.

TransparencyCodeList elements

Name Description Required Values
TransparencyCode The Transparency code associated with the item. No Type: xs:string

Weight

The weight value and unit of measurement.

Weight elements

Name Description Required Values
Value The weight of the object. Yes Type: xs:decimal
Unit The unit of measurement for weight. Yes Unit values: ounces, grams

Type: xs:string

Related topics