
# 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](/knowledge-base/labels/how-to/change-labels-with-claude). Full reference: [mcp.mixshift.io/developers#labels](https://mcp.mixshift.io/developers#labels) and [mcp.mixshift.io/developers#labels-write](https://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](https://build.mixshift.ai/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](https://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](/knowledge-base/builder-platform/getting-started/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](https://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](/knowledge-base/builder-platform/how-to/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 |