Metadata

metadata is a space of yours inside the seller. You store what you need as keys and values, then list the sellers filtering by that data.

Examples: the customer's plan, the region, their id in your CRM, tags like vip and b2b.

{
  "id": "6f0c…",
  "name": "Acme Store",
  "metadata": { "plan": "pro", "region": "south", "tags": ["vip", "b2b"] }
}

Every seller carries metadata. With nothing stored, it is {}. The value of each key can be any JSON: text, number, true/false, array or object.

WriteCopy Anchor Link

On create (POST /v1/sellers)Copy Anchor Link

Send metadata in the body. Without metadata, the seller is born with {}.

The null rule: null at the top level means "no such key". The key is simply not stored.

curl -X POST "$BACKEND_URL/v1/sellers" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Store", "metadata": { "plan": "pro", "region": null } }'

Response (region was not stored):

{ "id": "6f0c…", "name": "Acme Store", "metadata": { "plan": "pro" } }

On update (PATCH /v1/sellers/{id})Copy Anchor Link

PATCH merges at the top level. Only the keys you send change.

Before: { "plan": "free", "region": "south", "tags": ["vip"] }

Three points to avoid mistakes (and a warning: key order is not preserved, the database may return the keys in another order; do not rely on it):

• A missing metadata changes nothing. metadata: null clears everything. They are not the same.
• The merge is top-level only. An object you send replaces the previous one whole, with no joining inside. Before { "address": { "city": "Porto Alegre", "state": "RS" } }, you send { "address": { "state": "SC" } }, after { "address": { "state": "SC" } } (city is gone).
• null inside an object or array is a normal value. Only a null directly on a top-level key removes it.

curl -X PATCH "$BACKEND_URL/v1/sellers/$SELLER_ID" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "plan": "max", "region": null } }'

Filter the listCopy Anchor Link

GET /v1/sellers accepts metadata[key]=value. In curl, the brackets need -g (or --globoff); without it curl tries to interpret them. In code, you don't need it.

One key:

curl -g "$BACKEND_URL/v1/sellers?metadata[plan]=pro" \
  -H "Authorization: Bearer mk_your_api_key"

OR: repeating the same key accepts any of the values. Here, plan pro or max:

curl -g "$BACKEND_URL/v1/sellers?metadata[plan]=pro&metadata[plan]=max" \
  -H "Authorization: Bearer mk_your_api_key"

AND: different keys must all match. Here, plan pro and region south:

curl -g "$BACKEND_URL/v1/sellers?metadata[plan]=pro&metadata[region]=south" \
  -H "Authorization: Bearer mk_your_api_key"

The rules, in a list:

• Stored simple value (text, number, boolean): it must be equal.
• Stored array: it must contain at least one of the requested values.
• A number compares by value: metadata[stores]=3 and metadata[stores]=3.0 both find the number 3.
• Text compares exactly, case counts: metadata[stores]=3 finds the text "3", but does not find "3.0".
• true and false find the boolean and the text "true"/"false".
• A filter value with the NUL character (metadata[plan]=%00) returns 400. A huge number (metadata[x]=1e400) is not an error: it compares only as text.
• An object never matches. A key the seller does not have never matches.
• It combines with externalId and sort. pagination.totalItems counts only the filtered sellers.

Table of casesCopy Anchor Link

Each row is a seller with the metadata of the first column, and the filter of the second.

A malformed filter returns 400Copy Anchor Link

A filter that does not follow metadata[key]=value is refused, not ignored. If we ignored it, you would get every seller without noticing. These return 400: metadata=x, metadata[]=x, metadata[a][b]=x and metadata[__proto__]=x.

Filter limits:

LimitsCopy Anchor Link

They apply to the metadata after the merge, that is, to what the seller will have in the end.

The limit of 50 keys and the key-name format apply to the top-level keys. Keys inside nested objects are free: they count only for size and depth.

Depth: {"a":1} is 1 level, {"a":{"b":1}} is 2, and an array counts as a level.

A top-level null value does not count as a key: it only removes.

Also 400: text with the NUL character (\u0000) or an unpaired surrogate, in any value or nested key, and a number that does not fit JSON, like 1e400.

Big numbers: every number goes through the API's JSON, so an integer above 2^53 is stored with JavaScript precision: 12345678901234567890 becomes 12345678901234567000, and the filter compares the same way. If the id does not fit in a number, store it as text.

When it goes over a limitCopy Anchor Link

The response is 400 VALIDATION_ERROR, and nothing is stored. details lists the problems, with path starting at metadata. Example: a PATCH that would leave the seller with 51 keys.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request.",
    "details": [
      {
        "code": "custom",
        "path": ["metadata"],
        "message": "Metadata has 51 keys; the maximum is 50."
      }
    ]
  }
}

Other messages: Metadata text cannot contain the NUL character (\u0000) or an unpaired surrogate., Metadata has a number too large to store as JSON., Metadata keys are 1 to 40 letters, digits, "_" or "-". (invalid key, with the key name in path), Metadata is nested more than 5 levels deep. and Metadata takes 9000 bytes as JSON; the maximum is 8192.. See the general error format in Errors.