Validate an Amazon Seller ID Before You Call the Billing API

To validate an Amazon seller ID before calling /amazon-seller-review, check it locally against the seller ID shape seen in known IDs (an "A" followed by 12 or 13 more uppercase letters or digits) and reject known placeholders such as -1, N/A and blanks, plus Amazon's own first-party seller IDs. The endpoint's own gate only rejects a blank value with a free 400; every other bad input, including a well-formed ID that does not exist, reaches the Lambda as a billed 404.

Why does a bad seller ID get billed instead of rejected?

/amazon-seller-review takes sellerId and marketplaceId and its parameter gate only checks that both are present and non-blank; a seller ID of any other shape passes the gate and reaches the Lambda, which looks the seller up and returns a 404 when nothing matches. The credit is charged up front for every request that passes the gate, and a 404 is never refunded, so a typo or a leftover placeholder value costs exactly as much as a real lookup.

Which values should never reach the API?

Three endpoints return seller IDs that can be placeholders rather than real sellers: the Buy Box history marks an unheld period as -1 and an unknown new holder as -2, and a lookup with no featured offer answers N/A. None of those three are seller accounts, so none of them can ever return a real feedback page; sending them on is a guaranteed billed 404 known in advance. The bulk ASIN lookup guide and the seller ID lookup guide cover where real seller IDs come from.

seller_id_guard.py - reject bad seller IDs for free

"""Reject malformed, placeholder or first-party seller IDs before they reach a billed call."""
import re

from retry import get_with_retry
from sellermagnet import ApiError, new_session

SELLER_ID = re.compile(r"A[A-Z0-9]{12,13}")          # every seller ID seen so far: "A" + 12-13 upper/digits
PLACEHOLDERS = {"-1", "-2", "N/A", "Amazon"}          # history/offers fillers, never a real seller to look up

# Amazon's own first-party seller ID per store (website/blueprints config.amazonSellerIds, 2026-09-27):
# it has no feedback page, so /amazon-seller-review always answers it with a billed 404.
AMAZON_IDS = {
    "ATVPDKIKX0DER",   # amazon.com
    "A3DWYIK6Y9EEQB",  # amazon.ca
    "AVDBXBAVVSXLQ",   # amazon.com.mx
    "A1ZZFT5FULY4LN",  # amazon.com.br
    "A3P5ROKL5A1OLE",  # amazon.co.uk
    "A3JWKAKR8XB7XF",  # amazon.de
    "A1X6FK5RDHNB96",  # amazon.fr
    "A11IL2PNWYJU7H",  # amazon.it
    "A1AT7YVPFBWXBL",  # amazon.es
    "AN1VRQENFRJN5",   # amazon.co.jp
}


class LocalReject(Exception):
    """Raised before any HTTP request leaves the client: no credit is ever spent on these."""


def check_seller_id(seller_id: str) -> str:
    value = (seller_id or "").strip()
    if not value or value in PLACEHOLDERS:
        raise LocalReject(f"placeholder or blank seller ID: {value!r}")
    if value in AMAZON_IDS:
        raise LocalReject(f"{value} is Amazon's own ID: no feedback page, billed 404")
    if not SELLER_ID.fullmatch(value):
        raise LocalReject(f"not seller-ID shaped (\"A\" + 12-13 upper/digits): {value!r}")
    return value


def seller_review(session, seller_id: str, marketplace_id: str) -> dict:
    """Validate locally first; only a value that passes reaches the billed endpoint."""
    checked = check_seller_id(seller_id)
    return get_with_retry(session, "amazon-seller-review", sellerId=checked, marketplaceId=marketplace_id)


if __name__ == "__main__":
    session = new_session()
    candidates = [
        "A2I59UVTUWUFH0",              # real amazon.it seller (FACTS.md docs example)
        "-1",                          # Buy Box history placeholder: nobody held it
        "N/A",                         # lookup placeholder: no featured offer
        "",                            # blank field
        "ATVPDKIKX0DER",               # Amazon's own ID on amazon.com
        "a2i59uvtuwufh0",              # wrong case: never seen on a real seller ID
        "A2I59UVTUWUFH0XXXXXXXXXXXXXX",  # far too long: a copy-paste error
        "A9999999999999",              # right shape, but this seller does not exist
    ]
    for raw in candidates:
        try:
            data = seller_review(session, raw, "APJ6JRA9NG5V4")
            print(f"{raw!r:<34} -> {data.get('sellerFullName')}")
        except LocalReject as err:
            print(f"{raw!r:<34} -> rejected locally, no call made: {err}")
        except ApiError as err:
            print(f"{raw!r:<34} -> billed API error {err.status}: {err}")

Example output (one real ID, one existing-but-wrong ID, six locally rejected values)

'A2I59UVTUWUFH0'                   -> Example Shop IT
'-1'                               -> rejected locally, no call made: placeholder or blank seller ID: '-1'
'N/A'                              -> rejected locally, no call made: placeholder or blank seller ID: 'N/A'
''                                 -> rejected locally, no call made: placeholder or blank seller ID: ''
'ATVPDKIKX0DER'                    -> rejected locally, no call made: ATVPDKIKX0DER is Amazon's own ID: no feedback page, billed 404
'a2i59uvtuwufh0'                   -> rejected locally, no call made: not seller-ID shaped ("A" + 12-13 upper/digits): 'a2i59uvtuwufh0'
'A2I59UVTUWUFH0XXXXXXXXXXXXXX'     -> rejected locally, no call made: not seller-ID shaped ("A" + 12-13 upper/digits): 'A2I59UVTUWUFH0XXXXXXXXXXXXXX'
'A9999999999999'                   -> billed API error 404: 404: Seller not found

Which seller IDs belong to Amazon itself?

Amazon sells as a first-party seller under its own seller ID on every marketplace that has one; that ID has no public feedback page, so looking it up through /amazon-seller-review is always a billed 404. The offers endpoint already labels Amazon's own offer sellerId: "Amazon" instead of an ID, but Buy Box history and other sources carry the real ID directly, so a validator needs the list below, not just the string "Amazon".

Does a shape check remove every billed 404?

No. A value that matches the shape, one letter followed by 12 or 13 upper-case letters or digits, still has to exist as a real seller, and the API has no way to confirm that without a call. A9999999999999 in the example output above passes every local check and still comes back as a billed 404. The honest claim is that the check removes placeholders, typos and Amazon's own IDs for free; it cannot remove the one 404 that only the API can tell you about. The shape itself comes from the IDs seen so far, not a published Amazon spec, so widen the pattern if a real seller ID of a different length ever shows up. Caching that 404 so the same bad ID is never billed twice is covered in the seller ID lookup guide.

How do I check a seller ID without Python?

The same three checks work as a one-line shell test before a curl call: blank or a known placeholder, Amazon's own ID, or the wrong shape. Treat it as a quick guard for scripts and cron jobs, not a replacement for the Python check above, which also validates the marketplace ID.

Reject an obviously bad seller ID before curl spends a credit

SELLER_ID="A2I59UVTUWUFH0"
case "$SELLER_ID" in
  ""|-1|-2|N/A|Amazon|ATVPDKIKX0DER|A3DWYIK6Y9EEQB|AVDBXBAVVSXLQ|A1ZZFT5FULY4LN| \
  A3P5ROKL5A1OLE|A3JWKAKR8XB7XF|A1X6FK5RDHNB96|A11IL2PNWYJU7H|A1AT7YVPFBWXBL|AN1VRQENFRJN5)
    echo "skip: known placeholder or Amazon's own ID" ;;
  [A-Z][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9][A-Z0-9])
    curl -sG "https://sellermagnet-api.com/api/amazon-seller-review" --max-time 120 \
      --data-urlencode "api_key=$SELLERMAGNET_API_KEY" \
      --data-urlencode "sellerId=$SELLER_ID" \
      --data-urlencode "marketplaceId=APJ6JRA9NG5V4" ;;
  *) echo "skip: not seller-ID shaped" ;;
esac

Bottom line: the seller review endpoint only gives away a free 400 for a blank value, so catch placeholders, Amazon's own IDs and the wrong shape locally before every other call. The seller ID lookup guide builds the cache that handles the one 404 a shape check cannot predict, and a free account includes 150 credits to test both.