Returning the Referral Fee Structure via the Fees API

[ttimbul]

The Use Case

Trying to show fees based on a variable price, i.e. the user being able to enter a new amount (or dragging a slider) and correct fees to be shown. The Fees API (both GetMyFees and the batched endpoint) currently accepts a certain product and theoretical selling price as input, then spits out the fees based on that theoretical price.

If the price is changed, a new API request is required, and this would be unnecessary if you provided the referral fee structure instead of just a one-shot total. We could save a lot of server hits, bandwidth and round-trip time.

The Idea

Can this please be improved by also returning the following information:

• Category for the purposes of referral fee calculation, e.g. "Camera and Photo Accessories"
• Returning this category as part of an earlier call, such as getCatalogItem or listCatalogItems, or possibly by ensuring that it matches up with browseClassification in the summaries. This would allow the result to be reused
• The referral fee structure, encapsulating one or more percentage rates and their thresholds (see below).
• Whether those rates apply to the total selling price or to the portion of the price identified by each threshold level.

Note that the current categorisation

Referral Fee Percentage Structure
Example (as a child of FeesEstimate) - numbers are fictitious and just to illustrate the idea:

"ReferralFeeDetails": {
    "Category": "Clothing & Accessories",
    "Applicability": "PORTION",
    "Levels": [
        {
            "MaxPrice": 100.0,   //BigDecimal
            "Percentage": 12.5   //BigDecimal
        },
        {
            "Percentage": 8.0    //BigDecimal
        }
    ]
}

The above would mean in English:
"12.5% for the portion of the sales price up to and including 100, and 8% for the portion of the sales price of 100.01 and above."

Example 2:

"ReferralFeeDetails": {
    "Category": "Baby Products",
    "Applicability": "TOTAL",
    "Levels": [
        {
            "MaxPrice": 15.0,   //BigDecimal
            "Percentage": 8   //BigDecimal
        },
        {
            "Percentage": 15.0    //BigDecimal
        }
    ]
}

In English:
"8% on the whole of the sales price for items priced up to and including 15, or 15% on the whole of the sales price for items priced 15.01 and higher."

Example 3:

"ReferralFeeDetails": {
    "Category": "Camera and Photo",
    "Applicability": "TOTAL",
    "Levels": [
        {
            "Percentage": 12   //BigDecimal
        }
    ]
}

In English:
"12% flat rate on all products in this category"

Notes:

• Prices are in marketplace currency, although you could reuse the FeeAmount object to include the currency.
• Potentially there could be more than 2 levels. "MaxPrice" would be required for all but the last one.
• Levels should ideally be strictly ordered in ascending order of "MaxPrice" to make the result easy to parse and use.
• Prices and percentages must be formatted as Numeric/BigDecimal (not floating point) to ensure accuracy.
• Percentages should include any and all relevant digital sales taxes as applicable in the marketplace.

Alternatives

If this can't be included into the existing feesApi returns, another possibility might be to ensure that the referral fee category is returned by the Catalog API, and then making a separate (new) API call just to retrieve the referral fee structure. This could be either for a single category, or even better, a single call to load all referral fees for all categories on the marketplace in question. It could be cached API client-side for the duration of the interaction and no further API calls would be necessary for that duration.

Low-Price FBA Fees

Along similar lines, the new low-price FBA Fees need something similar. That way we don't need 5 requests just to figure out what the fees might be if a user is near the $10 threshold.

[ttimbul]

Another problem with the current one-shot model is that we don't even know which referral fee category an item belongs to (due to variations in sub-categorisation and certain exceptions).
For example "Office Devices (excluding 3D Printers)" - to obtain the referral fee percentage, even if we kept an internal mapping, we would need to fully understand the entire category tree in all markets. Due to occasional mis-classification this is very time-consuming and error-prone.

[ericblade]

Agree that this would be a fantastic improvement if we could calculate the fees reliably and correctly after one request for an asin/sku, without having to ping the server again.

Bit of a nitpick on the suggested implementation -- money should never be dealt with using floating point. Amazon doesn't seem to understand this, though.

[ttimbul]

That's why I explicitly commented them to be "BigDecimal" style - I'd be happy if they returned them as quoted Strings, so that there can be no doubt whatsoever about accuracy.

[steven-so]

Great suggestion, we have an immediate need for this.

Is there a good way to get the referral fee category as of today?

Right now we are trying to figure it out based on this endpoint:

GET /catalog/v0/categories
Operation: listCatalogCategories
https://developer-docs.amazon.com/sp-api/docs/catalog-items-api-v0-reference#categories

But, it seems to be pure guesswork to determine which referral fee category it actually belongs too.

[AbstractTek]

Hey, Did you work anything out with this Steven?

[steven-so]

Nothing noteworthy. We have manually mapped a small subset of categories that we care about for our business, but that is not scalable or maintainable. Glad to see this is under review from: @ritikacd

[ttimbul]

Exactly. There is no "single truth" to what belongs to what category.
But Amazon don't seem to care, or they pretend (successfully) not to care.
At the very least they could publish a document that maps every single browse tree node to the correct category.

[AbstractTek]

Did anyone figure out how to map the categories correctly for the referral fee? Wouldn't mind a chat with anyone with some experience in this. Thanks!

[ritikacd]

Did anyone figure out how to map the categories correctly for the referral fee? Wouldn't mind a chat with anyone with some experience in this. Thanks!

Hi @AbstractTek

You can retrieve estimated referral fees for each SKU using this report Referral Fee Preview Report. If you need to get the category for the SKU, you can use searchCatalogItems APIs passing the classificationIds query parameter to get the category classification path details.

I hope this helps!

Thanks,
Ritika
Selling Partner API Services

[ttimbul]

Thank @ritikacd, but this doesn't really help to map categories to referral fees. Half (most of?) the time the categories in classificationIds don't correspond directly to the referral fee categories.
It also doesn't cover exceptions, like "Pet Supplies - 15%, except 22% for veterinary diets". Well, which classification IDs are "veterinary diets"???

Remember, this is to help developers. Developers are expected to provide accurate data to their users (Amazon Marketplace Sellers and Vendors). At the moment it is impossible to do this without guessing what Amazon might have mapped as something or something else.

So why not add one more attibute 'referralFeeCategory' to the CatalogAPI and document which ones correspond to which fee class/percentage?

[ritikacd]

Thank @ritikacd, but this doesn't really help to map categories to referral fees. Half (most of?) the time the categories in classificationIds don't correspond directly to the referral fee categories. It also doesn't cover exceptions, like "Pet Supplies - 15%, except 22% for veterinary diets". Well, which classification IDs are "veterinary diets"???

Remember, this is to help developers. Developers are expected to provide accurate data to their users (Amazon Marketplace Sellers and Vendors). At the moment it is impossible to do this without guessing what Amazon might have mapped as something or something else.

So why not add one more attibute 'referralFeeCategory' to the CatalogAPI and document which ones correspond to which fee class/percentage?

Hello @ttimbul,

Thank you for proposing an enhancement to the Catalog Items API. We submitted the feature request for review. Once we receive additional information we will post an update.

Thanks,
Ritika
Selling Partner API Developer Services

[SohailChohan143]

Any Update on this ticket? did anyone figure out how we can get Referral Fee against each asin?

[ritikacd]

Hi @SohailChohan143

You can retrieve estimated referral fees for each SKU/ASIN using this report Referral Fee Preview Report.

Thanks,
Ritika
Selling Partner API Services

[ttimbul]

@ritikacd That completely misses the point. People want to know what potential referral fees they will be facing on any ASIN, not just the ones they are already selling. The whole point of an API is to expedite access to information.
Just to know what the fee on a particular item will be, why would anybody want to:

• Create a listing
• Download a report
• Parse that report

You might as well tell users to use the profit estimator, which is just as cumbersome and nigh impossible to automate.

So when is Amazon going to pull their head out of the sand and create something simple that allows us to tell which product belongs exactly to which referral fee category, without the guesswork and prayer that it currently involves?

[ritikacd]

Hi @ttimbul, If you are trying to look at fee estimates for an existing ASIN, you can retrieve that information using Product Fees APIs. Have you observed any discrepancy with this API?

[ttimbul]

@ritikacd The main problems with that API are its abysmal throttling rate (even on the batched version) and the fact that it returns an absolute figure for the referral fee. This is especially problematic where the referral fee category is layered, such as X% below a certain price point and Y% above a certain price point.

For some items it will be beneficial to sell them either just above or just below such a price point, or to avoid a certain range of prices, in order to minimise the impact of fees.

It becomes blatantly obvious at this point that you haven't even taken the time to read my original post. Had you done so, you would already have an understanding of the matter and why I proposed what I proposed.

You seem to be suggesting that it is perfectly adequate to make 4-5 API request per item in order to perform "what if" analysis. What if I change my price to $10.50 - API request. How about $11 - API request. Then try doing that for a few thousand items and it'll be Christmas again before the repricer has figured out that apparently Amazon are deliberately making it difficult to understand their fee structure. In the meantime you will have changed some of the other (fixed) fees so we'll have to start all over.

My proposal in this post was (and still is) to provide a means to return the rules that underpin the referral fee for each item. That way a single request will tell me all I need to know to work out what the fee might be at any selling price - saving API requests, round trip time, and a ton of frustration. It will also provide accuracy in the face of fee promotions.

For other fees, like monthly storage, an absolute figure makes sense, because it is pegged to attributes that don't change. For something that changes with something as volatile as price, the referral fee needs completely different treatment.
Basically your Fees API is clumsy and not fit for purpose.

But really it doesn't need to be per-item. All you need to tell us is exactly which referral fee category each item belongs to. Is that really too much to ask?

Why not add just one entry to the Fees API response - referral fee category? That would totally do it for me.

[MetaMan2023]

I was not aware there was a fee API (had never looked)... I'll have to check this out.

We currently pull the Amazon report daily that includes the Fee % as well as the FBA calculated fees as we use it in our API. We store this data in a database. One flaw with this report is sometimes it does not include some FBA items in the report (if there is a SKU issue or it's not currently stocked, it won't show on the report)

Does the Fees Report include the current FBA fees for the item (at current weight/dims) -- if so that would be fantastic... if not, I would request that the FBA fees be included in this API as well.

Also does the Fee API indicate if there would be a discount for $9.99 or less? It would be great if the results would include that information regardless of what the current price is. Some flag like "UNDER_10_DISCOUNT => 10%" in the results which would tell you what would be the discount if you were below that price.

Or more advanced to cover future options:

Discounts =
[
{
atOrBelowPrice => 9.99, ## price you need to be at or below
discountedRate => 10, ## percent
}
... ## other discounts if applicable
],

[ttimbul]

To use the Fees API you provide it with the ASIN and the selling price you're wanting fees for. You also tell it whether you're looking for FBA or Merchant Fulfilled. Optionally a fulfillment program can be provided. The choice here is basically between normal FBA (FBA_CORE) or the European Fulfilment Network (FBA_EFN).

The API then tells you all the fees that are applicable to that item at that price, such as monthly storage, fulfilment, referral, per-item fee if applicable. Fees include detailed information about promotions, etc. So that's great for a snapshot for a single price.

Problem, which I am trying to highlight here, is that the information is limited to the one price point that you feed in. Looking for low-price fees to see if you might be better off selling at 9.99 vs 10.01? Well, sorry, you'll have to make two API requests. Is that item also subject to 15% fees over $15 and 8% below? Well, if you want to figure out if you should sell at $14.99 or $15.01 or $9.99 or $10.01, you'll have to make four API requests.

Should I take advantage of the EFN in Europe? Oops, those requests just doubled again!

To make it more painful, the API is heavily throttled. On average you can only make 1 request per second.
There is also a batch API, which allows you to send 20 such requests at a time. However, on average you can only make 1 request every 2 seconds.
So if you're sneaky and combine the two in some clever way, you might be able to request 11 fees every second. But we already used 4 or 5 requests above, right?

So it works out as maybe 2 products checked per second, with latency/roundtrip probably closer to 1/s. If you're lucky and the API doesn't randomly throttle you despite not actually reaching the limit, as it seems to frequently do.

There's also that massive disclaimer at the top of the Use Case Guide:

Important

The estimated fees returned by this API are not guaranteed. Actual fees can vary.

[MetaMan2023]

Problem, which I am trying to highlight here, is that the information is limited to the one price point that you feed in. Looking for low-price fees to see if you might be better off selling at 9.99 vs 10.01? Well, sorry, you'll have to make two API requests. Is that item also subject to 15% fees over $15 and 8% below? Well, if you want to figure out if you should sell at $14.99 or $15.01 or $9.99 or $10.01, you'll have to make four API requests.

This makes sense -- so, without having used the API, it sounds like you can request multiple different ASIN/SKU in one call however you cannot make multiple requests on the same ASIN/SKU within the same call?

If so, I agree with you that it creates an issue.

I think the discount rate is solvable with some kind of price banding info returned -- but if there are ever FBA discounted rates it may get complicated to have a "formula" ... for example the old small and light I think resulted in a lower FBA rate.

Maybe a partial solution is that it would return some kind of price banding notes about discounts -- like price range A-B has a discount and B-C has a discount etc. then you would still have to make a call within those price bands to see what the "true" price is. It may be too complex to provide a "formula" for every type of discount but at least you would know what you need to request prices on.

Another solution is maybe you could set a flag requesting Amazon to provide not only at the price you requested but the price at every discount point... for example if you are requesting at $17.50 and you set the "DISCOUNT" flag, if the item does have a discount point at $9.99 and $14.99 they would also automatically return the fees at $9.99 and $14.99 prices. That may be the simplest -- a single call and Amazon would only return those points if they existed.