Identify a merchant: sellerId and legacySellerId

Almost everything on the Builder Platform acts for one Amazon merchant, and there are exactly two ways to name one. Picking the wrong one is an easy first-call mistake, and it is worth thirty seconds up front because it costs you twice: once on the API, where the call fails or resolves to the wrong merchant, and once in the warehouse, where the same mistake turns a fast query into a slow one without changing the answer.

The two identifiers

| Identifier | Type | What it is | | --- | --- | --- | | sellerId | string | Amazon's own merchant token, the A... or ENTITY... string. Stored in the warehouse as AmazonSellerID. | | legacySellerId | integer | The MixShift seller id. The durable unique key for exactly one merchant row, meaning one seller in one marketplace. Stored in the warehouse as SellerID. |

Both come back from GET /api/amazon/merchants, one row per account and marketplace.

There is no merchantId parameter. It has never existed on these endpoints. If you passed one, it was ignored, and the call either resolved to some other merchant or failed to resolve at all.

Which one to pass

Prefer legacySellerId whenever you have it. It identifies exactly one merchant row and takes precedence over everything else.

sellerId is fine on its own when the token maps to a single row. A seller who trades in more than one marketplace has several rows behind one token, so sellerId alone is ambiguous there. Add marketplace (US, CA, MX, and so on) to narrow it, or use legacySellerId and skip the question.

# Unambiguous: one merchant row.
curl -X POST https://mcp.mixshift.io/api/amazon/spapi/call \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation": "fulfillment_inbound.get_shipments",
       "legacySellerId": 12345,
       "query": {"QueryType": "SHIPMENT", "ShipmentStatusList": "RECEIVING,CLOSED"}}'

If a merchant cannot be resolved, the error tells you which identifiers the endpoint accepts and lists the candidate rows when the problem is ambiguity rather than a bad id.

The same distinction in the warehouse

Most seller-scoped warehouse tables carry both columns: an integer SellerID and a varchar AmazonSellerID. They identify the same seller and return the same rows, but they are not interchangeable for speed, because the indexes are generally built on the integer.

Filter on the integer SellerID. Filtering on AmazonSellerID often means the composite index that pairs the seller with a date is not used, which leaves a date range with nothing to seek on and scans every row for that seller.

spapi_settlement is the clearest case. The two indexes that matter here are:

• MIX_MAX_Record_IDX on (SellerID, Posted-date-time)
• Delete_Settlement_IDX on (AmazonSellerID, Settlement-id)

So a settlement query filtered by date only has an index to work with if it filters on the integer SellerID. Measured on one account, on one tenant database, with the identical one-month count returning exactly the same rows either way:

-- 13.4 seconds. The date predicate has no index to use.
SELECT COUNT(*) FROM spapi_settlement
WHERE AmazonSellerID = 'A1...'
  AND `Posted-date-time` >= '2026-07-01' AND `Posted-date-time` < '2026-08-01';

-- 0.37 seconds. Covered by MIX_MAX_Record_IDX.
SELECT COUNT(*) FROM spapi_settlement
WHERE SellerID = 12345
  AND `Posted-date-time` >= '2026-07-01' AND `Posted-date-time` < '2026-08-01';

Same answer, roughly 36 times the wait. That is what makes this worth knowing: nothing looks broken, so the usual next question is whether the table is indexed. It is. Just not for the column you filtered on. Index names and layouts live in each tenant's own database, so treat the shape as the lesson rather than the specific names.

Reach for AmazonSellerID when you are looking up a specific Settlement-id, which is what its index is for. Otherwise translate the token to the integer once at the start of your job:

SELECT ID FROM seller WHERE AmazonSellerID = 'A1...';

GET /api/amazon/merchants gives you the same mapping without a query.

This is a strong default rather than a universal law. If a query on a large table is slower than you expect, run EXPLAIN on it and check whether the chosen key actually covers your date predicate before concluding the table is the problem.

Related

• Work with live Amazon operations
• Query the warehouse
• Limits and guardrails
• Operation-level reference: mcp.mixshift.io/developers