# 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.

```bash
# 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:

```sql
-- 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:

```sql
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](/knowledge-base/builder-platform/how-to/work-with-live-amazon-operations)
- [Query the warehouse](/knowledge-base/builder-platform/how-to/query-the-warehouse)
- [Limits and guardrails](/knowledge-base/builder-platform/reference/limits-and-guardrails)
- Operation-level reference: [mcp.mixshift.io/developers](https://mcp.mixshift.io/developers)