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

FeePromotionNotification

Sellers using Amazon MWS can benefit from time-limited fee promotions. To receive notification of available fee promotions, sellers must subscribe to FeePromotion notification. When the seller initially signs up for the subscription and isEnabled is set to true, the seller receives all currently active promotions. Each promotion is sent as a single message. Subsequent promotion notifications are sent when the promotion becomes active.

FeePromotion notification is made up of a set of data fields describing the details of that promotion. All qualifying criteria for each promotion will be described in those data fields.

Note: The estimated fees returned by this API are not guaranteed. Actual fees may vary. For more information on fees, see Selling on Amazon Fee Schedule and FBA features and fees on Seller Central.

Availability

This notification is available in all marketplaces.

FeePromotionNotification

Contains the full details of an active fee promotion for the given merchant/marketplace.

This is the root element of the FeePromotionNotification.xsd schema:

Name Description
FeePromotionNotification The root element of the FeePromotion notification payload.

FeePromotionNotification Attributes

Each FeePromotionNotification element is made up of the following data objects:

Name Description Required Value
FeePromotionType The type of promotion. Yes Values: Pricing, SelectionASIN, or SelectionCategory. Additional types may become available in the future.

Type: xs:string

FeePromotionTypeDescription Provides more details on the purpose of a promotion. No A friendly, localized string description. Useful for integrators to display on a UI.

Type: xs:string

MarketplaceId The promotion applies to this marketplaceId. Yes Type: xs:string
MerchantId The promotion applies to this merchantId. Yes Type: xs:string
IdentifierList A list of items to which this promotion applies. Yes Type: List of type Identifier
PromotionActiveTimeRange The range of time when this promotion is active. Yes Type: PromotionActiveTimeRange
PromotionInformation An object containing additional details about the promotion. A fee estimate is included if applicable. Yes Type: PromotionInformation

Identifier

A description of an item to which this promotion applies.

Identifier Attributes

The following table describes the attributes of an item from the IdentifierList element:

Name Description Required Value
IdentifierType The merchant identifier type for which this promotion will apply to. Yes For example: ASIN, SKU, Browse node, Brand.

Type: xs:string

IdentifierValueList The merchant identifier values to which this promotion will apply. Yes For example: the merchant's actual ASINs or SKUs, an actual list of brands (like Nike), an actual list of browse nodes.

Type: List of type IdentifierValue

IdentifierValue

A description of identifier values to which this promotion applies.

IdentifierValue Attributes

Name Description Required Value
IdentifierValueId The actual browse node ID, actual ASIN/SKU, or brand value. Yes Type: xs:string
IdentifierValueFriendlyName The friendly name of the ID value. No Only relevant/populated for things like browse nodes. For example, this would be a browse node's friendly name.

Type: xs:string

PromotionActiveTimeRange

The range of time when this promotion is active.

PromotionActiveTimeRange Attributes

The following table shows the child elements of the PromotionActiveTimeRange element:

Name Description Required Value
EffectiveFromDate Date (inclusive) when the promotion becomes active. Yes Type: xs:dateTime
EffectiveThroughDate Date (exclusive) when the promotion has ended. Yes Type: xs:dateTime

PromotionInformation

An object containing additional details about the promotion. A fee estimate is included if applicable.

PromotionInformation Attributes

The following table shows the child elements of the PromotionInformation element:

Name Description Required Value
FeeType The fee type which is being discounted in this promotion. Yes Allowed Fee types: ReferralFee, VariableClosingFee, PerItemFee, FBAFees, FBAPickAndPack, FBAWeightHandling, FBAOrderHandling, FBADeliveryServicesFee.

Type: xs:string

FeeDiscountType The type of promotion you will be receiving for your fees. Yes Either Fixed, Discount, or Percentage points off.

Type: xs:string

PriceThreshold The qualifying threshold offer price, or less, that must be met for the promotion to apply. No

Type: MoneyType

FeeDiscountMonetaryAmount The amount you will receive off of your fees if the FeeDiscountType involves a monetary amount. No If the FeeDiscountType involves a monetary amount, this value will be populated.

Type: MoneyType

FeeDiscountValue The percentage discount of your fees if the FeeDiscountType involves a non-monetary amount. No If the FeeDiscountType involves a non-monetary amount, this value will be populated.

Type: xs:BigDecimal

FeesEstimate The fee estimate for this promotion, if it is available. The estimate assumes that all condition required for the promotion have been met. No Type: FeesEstimate

FeesEstimate

The details of the fee estimate for this promotion, if it is available.

FeesEstimate Attributes

The following table shows the child elements of the FeesEstimate element:

Name Description Required Value
TimeOfFeesEstimated The date time when the fees were estimated. Yes Type: xs:dateTime
TotalFeesEstimate The total amount of fees if the price is lowered to or below the price threshold. Yes Type: MoneyType
FeeDetailList An itemization of the TotalFeesEstimate). Yes Type: List of FeeDetail

FeeDetail

The FeeDetail data type is a container for an itemization of fee estimates. It can contain other FeeDetail elements as needed.

FeeDetail Attributes

The following table shows the attributes of a FeeDetail element:

Name Description Required Value
FeeType The type of fees charged. Yes Allowed Fee types: ReferralFee, VariableClosingFee, PerItemFee, FBAFees, FBAPickAndPack, FBAWeightHandling, FBAOrderHandling, FBADeliveryServicesFee.

Type: xs:string

FeeAmount The fee amount corresponding to the fee type. Yes Type: MoneyType
FeePromotion The fee promotion amount corresponding to the fee type. No Type: MoneyType
TaxAmount The tax calculated over fee that would be charged to the seller. No Type: MoneyType
FinalFee The final fee that would be charged to the seller. Yes The FeeAmount minus the FeePromotion.

Type: MoneyType

IncludedFeeDetailList A structured list of FeeDetail that contains the itemization of a specific fee type. No Type: List of FeeDetail

Examples

Amazon MWS returns an XML file that contains the response to a successful request or subscription. If the request is unsuccessful, the main response element is ErrorResponse. For more information, see Response format in the Amazon MWS Developer Guide.

Example notification 1

ASIN-level pricing promotion (meaning: lower your price to receive a discount off of your fees):

Show example code Hide example code 

<?xml version="1.0"?>
<FeePromotionNotification xmlns="http://mws.amazonservices.com/schema/Subscription/2011-10-01>
    <MerchantId>ATEXAMPLERGR</MerchantId>
    <MarketplaceId>ATVPDKIKX0DER</MarketplaceId>
    <FeePromotionType>Pricing</FeePromotionType>
    <FeePromotionTypeDescription>A promotion encouraging you to lower your price on an item to receive lower fees.</FeePromotionTypeDescription>
    <PromotionActiveTimeRange>
        <EffectiveFromDate>2015-07-19T23:15:11.859Z </EffectiveFromDate>
        <EffectiveThroughDate>2015-08-19T23:15:11.859Z </EffectiveThroughDate>
    </PromotionActiveTimeRange >
    <IdentifierList>
        <Identifier>
            <IdentifierValueList>
                <IdentifierValue>
                    <IdentifierValueId>B0002GTTRC</IdentifierValueId>
                </IdentifierValue>
            </IdentifierValueList>
            <IdentifierType>ASIN</IdentifierType>
        </Identifier>
    </IdentifierList>
    <PromotionInformationList>
        <PromotionInformation>
            <FeeType>ReferralFee</FeeType>
            <FeeDiscountType>Percentage points off</FeeDiscountType>
            <FeeDiscountValue>6.0</FeeDiscountValue>
            <PriceThreshold>
                <CurrencyCode>USD</CurrencyCode>
                <Amount>100.00</Amount>
            </PriceThreshold>
            <FeesEstimate>
                <TimeOfFeesEstimated>2015-07-12T23:15:11.859Z </TimeOfFeesEstimated>
                <TotalFeesEstimate>
                    <CurrencyCode>USD</CurrencyCode>
                    <Amount>6.30</Amount>
                </TotalFeesEstimate>
                <FeeDetailList>
                    <FeeDetail>
                        <FeeType>ReferralFee</FeeType>
                        <FeeAmount>
                            <CurrencyCode>USD</CurrencyCode>
                            <Amount>10.00</Amount>
                        </FeeAmount>
                        <FeePromotion>
                            <CurrencyCode>USD</CurrencyCode>
                            <Amount>6.00</Amount>
                        </FeePromotion>
                        <FinalFee>
                            <CurrencyCode>USD</CurrencyCode>
                            <Amount>4.00</Amount>
                        </FinalFee>
                    </FeeDetail>
                    <FeeDetail>
                        <FeeType>VariableClosingFee</FeeType>
                        <FeeAmount>
                            <CurrencyCode>USD</CurrencyCode>
                            <Amount>0.00</Amount>
                        </FeeAmount>
                    </FeeDetail>
                    <FeeDetail>
                        <FeeType>PerItemFee</FeeType>
                        <FeeAmount>
                            <CurrencyCode>USD</CurrencyCode>
                            <Amount>0.00</Amount>
                        </FeeAmount>
                    </FeeDetail>
                    <FeeDetail>
                        <FeeType>FBAFees</FeeType>
                        <FeeAmount>
                            <CurrencyCode>USD</CurrencyCode>
                            <Amount>2.30</Amount>
                        </FeeAmount>
                        <IncludedFeeList>
                            <FeeDetail>
                                <FeeType>FBAOrderHandling</FeeType>
                                <FeeAmount>
                                    <CurrencyCode>USD</CurrencyCode>
                                    <Amount>1.00</Amount>
                                </FeeAmount>
                            </FeeDetail>
                            <FeeDetail>
                                <FeeType>FBAPickAndPack</FeeType>
                                <FeeAmount>
                                    <CurrencyCode>USD</CurrencyCode>
                                    <Amount>0.30</Amount>
                                </FeeAmount>
                            </FeeDetail>
                            <FeeDetail>
                                <FeeType>FBAWeightHandling</FeeType>
                                <FeeAmount>
                                    <CurrencyCode>USD</CurrencyCode>
                                    <Amount>1.00</Amount>
                                </FeeAmount>
                            </FeeDetail>
                        </IncludedFeeList>
                    </FeeDetail>
                </FeeDetailList>
            </FeesEstimate>
        </PromotionInformation>
    </PromotionInformationList>
</FeePromotionNotification>
<ResponseMetadata>
    <RequestId>21534f03-e7e3-4d9a-9bea-0e15add3326d</RequestId>
</ResponseMetadata>

↑ Top

Example notification 2

ASIN-level selection promotion (meaning: add this ASIN to your selection to receive a discount off of your fees):

Show example code Hide example code 

<?xml version="1.0"?>
<FeePromotionNotification xmlns="http://mws.amazonservices.com/schema/Subscription/2011-10-01">
    <MerchantId>ATEXAMPLERGR</MerchantId>
    <MarketplaceId>ATVPDKIKX0DER</MarketplaceId>
    <FeePromotionType>SelectionASIN</FeePromotionType>
    <FeePromotionTypeDescription>A promotion encouraging you to list a particular ASIN or set of ASINs.</FeePromotionTypeDescription>
    <PromotionActiveTimeRange>
        <EffectiveFromDate>2015-07-19T23:15:11.859Z </EffectiveFromDate>
        <EffectiveThroughDate>2015-08-19T23:15:11.859Z </EffectiveThroughDate>
    </PromotionActiveTimeRange >
    <IdentifierList>
        <Identifier>
            <IdentifierValueList>
                <IdentifierValue>
                    <IdentifierValueId>B0002GTTRC</IdentifierValueId>
                </IdentifierValue>
            </IdentifierValueList>
            <IdentifierType>ASIN</IdentifierType>
        </Identifier>
    </IdentifierList>
    <PromotionInformationList>
        <PromotionInformation>
            <FeeType>ReferralFee</FeeType>
            <FeeDiscountType>PercentagePoints</FeeDiscountType>
            <FeeDiscountValue>6.0</FeeDiscountValue>
        </PromotionInformation>
    </PromotionInformationList>
</FeePromotionNotification>
<ResponseMetadata>
    <RequestId>21534f03-e7e3-4d9a-9bea-0e15add3326d</RequestId>
</ResponseMetadata>

↑ Top

Example notification 3

Category-level selection promotion (meaning: add this category to your selection to receive a discount off your fees):

Show example code Hide example code 

<?xml version="1.0"?>
<FeePromotionNotification xmlns="http://mws.amazonservices.com/schema/Subscription/2011-10-01">
    <MerchantId>ATEXAMPLERGR</MerchantId>
    <MarketplaceId>ATVPDKIKX0DER</MarketplaceId>
    <FeePromotionType>SelectionCategory</FeePromotionType>
    <FeePromotionTypeDescription>A promotion encouraging you to begin selling new items in a  brand, category or area to increase sales..</FeePromotionTypeDescription>
    <PromotionActiveTimeRange>
        <EffectiveFromDate>2015-07-19T23:15:11.859Z </EffectiveFromDate>
        <EffectiveThroughDate>2015-08-19T23:15:11.859Z </EffectiveThroughDate>
    </PromotionActiveTimeRange >
    <IdentifierList>
        <Identifier>
            <IdentifierValueList>
                <IdentifierValue>
                    <IdentifierValueId>123456789</IdentifierValueId>
                    <IdentifierValueFriendlyName>Espresso Machines</IdentifierValueFriendlyName>
                </IdentifierValue>
                <IdentifierValue>
                    <IdentifierValueId>987654321</IdentifierValueId>
                    <IdentifierValueFriendlyName>Espresso Accessories</IdentifierValueFriendlyName>
                </IdentifierValue>
            </IdentifierValueList>
            <IdentifierType>BrowseNode</IdentifierType>
        </Identifier>
    </IdentifierList>
    <PromotionInformationList>
        <PromotionInformation>
            <FeeType>ReferralFee</FeeType>
            <FeeDiscountType>PercentagePoints</FeeDiscountType>
            <FeeDiscountValue>6.0</FeeDiscountValue>
        </PromotionInformation>
    </PromotionInformationList>
</FeePromotionNotification>
<ResponseMetadata>
    <RequestId>21534f03-e7e3-4d9a-9bea-0e15add3326d</RequestId>
</ResponseMetadata>

↑ Top