List sellers

Returns the sellers of your account in pages, from the newest to the oldest by default. Use it to sync your records with ours or to build a list on your screen.

SortingCopy Anchor Link

sort picks the order. One parameter; a leading minus means descending.

Ties are broken by id, so the order is stable across pages.

curl "$BACKEND_URL/v1/sellers?sort=name&pageSize=50" \
  -H "Authorization: Bearer mk_your_api_key"

FilteringCopy Anchor Link

externalId returns only the seller with that external id, compared exactly. It is unique within your account, so data has one item or none, and pagination.totalItems is 1 or 0. It is the way to find your customer's record from your own id without storing ours.

curl "$BACKEND_URL/v1/sellers?externalId=customer-123" \
  -H "Authorization: Bearer mk_your_api_key"

metadata[key]=value filters by the seller's metadata. See Metadata.

Go through all pagesCopy Anchor Link

1. Ask for page 1 (page=1). Use pageSize for the size (1 to 100, default 20).
2. Read the pagination of the response: totalPages tells how many pages there are, and hasNext tells if there is one after this.
3. While hasNext comes back true, ask for page + 1.

# first page
curl "$BACKEND_URL/v1/sellers?page=1&pageSize=50" \
  -H "Authorization: Bearer mk_your_api_key"

# next page
curl "$BACKEND_URL/v1/sellers?page=2&pageSize=50" \
  -H "Authorization: Bearer mk_your_api_key"

With 3 sellers and pageSize=2, page 1 brings 2 sellers in data and this pagination:

{
  "page": 1,
  "pageSize": 2,
  "totalItems": 3,
  "totalPages": 2,
  "hasNext": true,
  "hasPrev": false
}

A page after the last oneCopy Anchor Link

Asking for a page past the end (in the example, page=3) is not an error. The response is 200 with data: [] and a pagination with the real totals, which show where the list ends.

Common errorsCopy Anchor Link

• 400 VALIDATION_ERROR: page below 1, pageSize outside 1 to 100, a value that is not an integer, a sort outside the table above, or an empty externalId. details points at the wrong parameter (path: ["page"]).

A seller created while you readCopy Anchor Link

If a seller is created while you go through the pages, the others move down one position. The last seller of a page shows up again at the start of the next one. Use the id so you don't process the same seller twice.