Skip to main content

Change labels from your own code or agent

This is the developer guide to labels: read them, and change them in bulk, over REST or with the labels_* tools from an AI client over MCP. If you would rather just tell Claude what to change, see Change labels with Claude. Full reference: mcp.mixshift.io/developers#labels and mcp.mixshift.io/developers#labels-write.

Before you start

  • Base URL: https://mcp.mixshift.io, with Authorization: Bearer <token>.
  • Turned on per database. MixShift turns label changes on for each customer database. Until then a call answers 403 not_enabled; ask MixShift to turn it on.
  • Credential. A person's own sign-in (the plugin and AI connectors) can change labels, except people with the Viewer role (or the older Member role) in your organization. A shared login with no individual member sign-in: everyone on it can. A service credential for your own code or automation is made on Machine credentials (organizations with member sign-in; an owner, admin or builder makes it), where you switch on the "Change labels" permission (labels:write). An organization still on one shared team login makes it at mcp.mixshift.io/admin and ticks "Also grant Labels write access". A credential is read-only for labels unless that permission is on. Exchange it for a token as described in Get access; every change it makes is recorded under the credential's label, not a person. An admin can also turn label changes off for a person at mcp.mixshift.io/admin. A credential limited to named accounts cannot read labels at all.
  • Scope: writes need labels:write.
  • Errors are always { "ok": false, "kind", "friendly" }; branch on kind.

Finding the account id

account is the MixShift seller id: one merchant in one marketplace, of a live, non-agency account in your own database. Any other id answers 404 not_found. List yours with GET /api/amazon/merchants (one row per account and marketplace).

Fields

Name Key Items Campaigns
Item Group item_group yes yes
Item Nickname nickname yes no
Brand brand yes yes
Parent ASIN parent_asin yes no
Item Label 1, Item Label 2 label_1, label_2 yes yes
Tag 1 to Tag 4 tag_1 to tag_4 yes yes
Manager manager no yes
Objective objective no yes

You can give a field your own name per account (up to 80 characters, for example "Collection" for label_1). The API and Claude use it; MixShift's report screens keep the standard name.

Reads

REST MCP tool What it does
GET /api/labels/state labels_state whether label changes are on for you
GET /api/labels/fields?account=&entity=item|campaign labels_fields the fields, your display_name, and the values in use with counts
GET /api/labels/items?account=&field=&value=&cursor=&limit= labels_search items by field value. limit 1 to 200 (default 50). Each set field is { value, sync, updated_at }
POST /api/labels/items/lookup with { "account", "ids": [...] } labels_get up to 500 ASINs: which MixShift has seen and which not
GET /api/labels/campaigns... and POST /api/labels/campaigns/lookup labels_get, labels_search the same for campaigns (campaign ids as digit strings)
GET /api/labels/drift?account=&entity=&cursor=&limit= labels_drift items whose rows in different marketplaces disagree on a field (for example a new SKU that took another marketplace's value), with what MixShift holds
GET /api/labels/changes?account=&since=&cursor=&limit= labels_changes a forward feed of changes, oldest first. It settles for two minutes, so keep next_cursor and call again from it

A changed value reads sync: "pending" until it has been copied into MixShift's reports, then synced, or failed if it could not be copied. Normally that takes a few minutes. Edits your team makes directly in MixShift's own screens still work and are picked up within about 15 minutes (except on a field whose change is still pending); in the change feed their source is the literal value dash, meaning an edit made in MixShift's own screens.

Preview, then commit

Only label value changes preview first. A field name (display name) applies at once, with no preview.

1. Preview

POST /api/labels/changes/preview

{ "account": 1234,
  "entity": "item",
  "selection": { "ids": ["B0EXAMPLE01", "B0EXAMPLE02"] },
  "set": { "label_1": "Spring 2027", "tag_2": null },
  "scope": "region" }
  • selection is one of: { "ids": [...] } (up to 1,000), { "filter": { "field", "value" } } (every item or campaign whose field equals the value, resolved at preview time and frozen), or { "rename": { "field", "from", "to" } } (rename has no set).
  • set maps a field key to a new value, or to null to clear it. Fields you leave out are untouched.
  • scope, items: region (the default: every marketplace of that seller account) or all (every account of the same type, every Seller account or every Vendor account, in your database). Campaigns: marketplace, the only scope accepted, because a campaign belongs to one account.
  • Asking for one marketplace on items (marketplace) is refused with 422 scope_not_supported and nothing changes. MixShift keeps an ASIN's label the same across the marketplaces of one seller account so a report grouped by a label never splits an ASIN.
  • An ASIN sold under two of your seller accounts has a label on each; a change on one account does not reach the other unless you use all. The preview names every account it reaches.

A preview changes nothing. It answers (shortened here; the full body carries the detail below):

{ "ok": true,
  "change_set_id": "<id>",
  "expires_at": "<24 hours from now>",
  "approval_hash": "<hash>",
  "warnings": [ ... ] }

The preview lists counts per account, what was dropped and why (for example an ASIN MixShift has not pulled yet), a before and after sample, and warnings (for example a value that differs only in capitals from one already in use). Values are trimmed, may not be blank or contain control characters, and may not be longer than the field holds. A preview expires after 24 hours, and at most 25 uncommitted previews can be open at a time.

2. Commit

POST /api/labels/changes/{id}/commit with { "approval_hash": "<hash from the preview>" }

The commit applies exactly what was previewed, in one transaction. An item someone changed between preview and commit is left alone and reported as stale. ok: true comes back only when nothing was stale or refused; otherwise the answer is partially_applied, stale or failed (status 409 or 422) with needs_attention listing what to look at. Committing twice returns the stored result and writes nothing.

3. Cancel, undo, history

Call What it does
POST /api/labels/changes/sets/{id}/cancel discards an open preview
POST /api/labels/changes/sets/{id}/undo makes a new preview that puts the earlier values back; commit it like any change. An item changed again since is left alone and reported
GET /api/labels/changes/sets?account=&limit=&before= recent changes, with who made them
GET /api/labels/changes/sets/{id} one change
PUT /api/labels/fields/names with { account, entity, field, name } give a field your own name on one account
DELETE /api/labels/fields/names?account=&entity=&field= remove it

Limits

  • 1,000 ASINs or campaigns per change, 500 per lookup, 200 per page of reads.
  • 25 open previews at a time; a preview lives 24 hours.
  • Only items and campaigns MixShift has already seen can be changed.
  • A field name is at most 80 characters.

From ChatGPT, Claude, Cursor or Codex (MCP)

Connect as described in Connect AI tools over MCP. The same calls appear as tools: reads labels_state, labels_fields, labels_get, labels_search, labels_drift, labels_changes; writes labels_preview, labels_commit, labels_undo, labels_change_set, labels_set_display_name. An agent should preview, show the person the counts and the scope, and commit only after the person confirms that exact preview in a separate turn.

Errors

kind status meaning
not_enabled 403 label changes are not turned on for your database; ask MixShift
insufficient_scope 403 your credential lacks the read scopes, or labels:write for a change
not_found 404 no such account in your database
bad_params 400 a parameter is missing or malformed
invalid_value 422 a value was refused; the answer lists every problem
empty_selection 422 the selection matched nothing
too_many_entities 422 more than 1,000 in one change; split it
commit_too_large 422 too big to commit as one change; split it, do not retry as is
too_many_open_previews 429 25 previews are open; commit or cancel some
change_set_not_found 404 no such preview or change
approval_mismatch 409 the approval_hash is not the one this preview gave
change_set_expired 409 the preview is older than 24 hours; preview again
change_set_cancelled 409 the preview was cancelled
scope_not_supported 422 the scope is not offered for this entity (for example one marketplace on items)
account_not_accessible 403 your credential cannot reach that account
nothing_to_undo 422 that change changed nothing (a preview, a cancelled one, or nothing applied), so there is nothing to put back
invalid_name 422 the field name was refused
name_in_use 409 another field on that account already has that name, or it is another field's standard name
Still have questions?
Ask Shifty

Shifty is the MixShift docs assistant. Pick a question or open the chat for anything else.