Amazon Services
Amazon Marketplace Web Service (Amazon MWS) Documentation
Amazon MWS Documentation

Merchant Fulfillment Datatypes

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

Datatype Description
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.
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.
Shipment The details of a shipment, including the shipment status.
ShipmentRequestDetails Shipment information required for requesting shipping service offers or for creating a shipment.
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.

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 only in the Canada, US, and UK marketplaces. 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
TransparencyCodeList List of Transparency codes. No Type: TransparencyCodeList

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

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.

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

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

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: oz (for ounces) or g (for grams)

Type: xs:string

Related topics