*REST API › Endpoint reference › Catalog & inventory › Items* # Update the accessories of an item > Applies operations on the accessories list. READ `mode` BEFORE CALLING: with `merge` —the default— the operations are deltas and what you do not name is kept; with `replace` the list sent is the final one and EVERYTHING absent is DELETED. An accessory can be another catalog item or a custom one with its name and its price. Returns the full item, with `accessoryIds` as they now stand, the same projection as its GET. `PUT /api/v1/items/{itemId}/accessories` — scope `items:write` Scope: `items:write` · 120/min · Strict tenancy · Idempotency-Key · If-Match · MCP: `filmo_items_accessories_update` ## Authorizations Bearer API key with the scope below. `items:write` ## Headers | Name | Type | Required | Description | | --- | --- | --- | --- | | `Idempotency-Key` | string | No | Unique identifier of the request, chosen by the client (a UUID works). Between 1 and 255 characters: an empty header is rejected with 400 `validation_error`, because the client would believe itself protected. Repeating the same key with the SAME body within 24 h returns the stored response without executing again, with the `Idempotent-Replay: true` header. With a DIFFERENT body it returns 422. It is the safe way to retry after a network timeout. | | `If-Match` | string | No | Optimistic locking: the `ETag` you read from the resource (or `*`). If the resource changed since, the write is rejected with `412 precondition_failed` before doing anything; read it again and retry. Without the header the write always proceeds. | ## Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `itemId` | string | Yes | Item identifier. | ## Body Body schema: `ItemAccessoriesBody` | Name | Type | Required | Description | | --- | --- | --- | --- | | `mode` | string | No | merge (default): operations are deltas and whatever you do not name is kept. replace: the list sent is the final list and everything absent IS DELETED. `merge`, `replace` | | `targetItemVariantId` | string | No | Variant of the item the accessories apply to. | | `operations` | object[] | Yes | Operations to apply. At least one. | | `operations.accessoryId` | string | No | Existing accessory. Required to update or delete. | | `operations.action` | string | No | What to do. If omitted: with accessoryId it updates, without it it creates. `create`, `update`, `delete` | | `operations.accessory` | object | Yes | Accessory data. | | `operations.accessory.itemId` | string | No | Item that acts as the accessory. Omit it for a custom one. | | `operations.accessory.quantity` | integer | Yes | Quantity of the accessory. | | `operations.accessory.free` | boolean | Yes | true if the accessory is not charged. | | `operations.accessory.default` | boolean | Yes | true if it is added automatically when the item is put in an order. | | `operations.accessory.accessoryVariantId` | string | No | Variant of the accessory. | | `operations.accessory.isCustom` | boolean | No | true for an accessory that is not in the catalog. | | `operations.accessory.customName` | string | No | Name of the custom accessory. | | `operations.accessory.customPrice` | number | No | Unit price of the custom accessory. | | `operations.accessory.position` | integer | No | Display order. | ## Request examples *Update the accessories of an item* **cURL** ```bash curl https://app.filmo.io/api/v1/items/item_8f2a1c/accessories \ --request PUT \ --header "Authorization: Bearer $FILMO_API_KEY" \ --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \ --header 'Content-Type: application/json' \ --data '{ "mode": "merge", "operations": [ { "action": "create", "accessory": { "itemId": "itm_00311", "quantity": 2, "free": true, "default": true } }, { "action": "delete", "accessoryId": "acc_00088", "accessory": { "itemId": "itm_00204", "quantity": 1, "free": false, "default": false } } ] }' ``` **Node.js** ```javascript fetch('https://app.filmo.io/api/v1/items/item_8f2a1c/accessories', { method: 'PUT', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ mode: 'merge', operations: [ { action: 'create', accessory: { itemId: 'itm_00311', quantity: 2, free: true, default: true } }, { action: 'delete', accessoryId: 'acc_00088', accessory: { itemId: 'itm_00204', quantity: 1, free: false, default: false } } ] }) }) ``` **Python** ```python import uuid import requests requests.put( "https://app.filmo.io/api/v1/items/item_8f2a1c/accessories", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "mode": "merge", "operations": [ { "action": "create", "accessory": { "itemId": "itm_00311", "quantity": 2, "free": True, "default": True } }, { "action": "delete", "accessoryId": "acc_00088", "accessory": { "itemId": "itm_00204", "quantity": 1, "free": False, "default": False } } ] } ) ``` ## Response Response schema: `ItemDetailDto` | Status | Description | | --- | --- | | 200 | Successful response. | | 400 | Invalid request (validation_error): malformed query or body. `errors[]` lists every offending field with its stable code. | | 401 | Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). | | 403 | Not allowed (insufficient_scope: the API key does not have the required scope, named in `requiredScope`; forbidden: the owner of the key lacks the permission the operation requires). `insufficient_scope` is answered before the request counts against the rate limit, so it carries no `RateLimit-*` headers; `forbidden` does. | | 404 | Resource not found (not_found): it does not exist or is outside the scope of the API key. | | 409 | Conflict (conflict): the current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation. | | 412 | Precondition failed (precondition_failed): the `If-Match` entity tag does not match the current representation. Read the resource again and retry. | | 422 | Idempotency-Key reused (idempotency_key_reused): the same key was used before with a different body. Change the key. | | 429 | Rate limit exceeded (rate_limited): retry after `Retry-After` seconds; `RateLimit-*` says which quota ran out. | | 500 | Internal error (internal_error). | **200** | Name | Type | Description | | --- | --- | --- | | `data` | object | The item in full, as returned by the API. | | `data.id` | string | Unique identifier of the item. | | `data.name` | string | Item name. | | `data.sku` | string | SKU reference of the item; null if not recorded. | | `data.description` | string | Item description; null if not recorded. | | `data.orderInfo` | string | Additional information for the order (preparation/delivery notes); null if not recorded. | | `data.ean` | string | EAN/barcode; null if not recorded. | | `data.itemType` | string | Item type: fixed (simple item) or variant (item with variants). `fixed`, `variant` | | `data.stockCalculationMethod` | string | Stock calculation method: bulk (in bulk, by quantity) or serialized (by serialized items). `bulk`, `serialized` | | `data.collectionId` | string | Identifier of the collection it belongs to; null if it is in none. | | `data.collectionName` | string | Name of the collection it belongs to; null if it is in none. | | `data.images` | string[] | URLs of the item images. | | `data.salePrice` | string | Sale price as a decimal string "1234.50" (ROUND_HALF_UP); null if it has none. | | `data.depositValue` | string | Deposit amount as a decimal string "1234.50" (ROUND_HALF_UP); null if it has none. | | `data.minStock` | number | Minimum stock configured for alerts; null if not configured. | | `data.serializedItemsCount` | number | Number of serialized items registered for the item. | | `data.pricingSettings` | object | Rental pricing configuration; null if not configured. | | `data.pricingSettings.type` | string | Pricing mode: periodPrice (price per period), fixedPrice (fixed price) or pricingStructure (pricing structure); null if the item has none configured. `periodPrice`, `fixedPrice`, `pricingStructure` | | `data.pricingSettings.price` | string | Base rental price as a decimal string "1234.50" (ROUND_HALF_UP); null if not applicable. | | `data.pricingSettings.period` | string | Period unit of the price: hour, day, week or month; null if the item has none configured. `hour`, `day`, `week`, `month` | | `data.insuranceEnabled` | boolean | Whether the item allows insurance. | | `data.discountEnabled` | boolean | Whether the item allows discounts. | | `data.bufferBefore` | number | Buffer time reserved before the rental; null if not applicable. | | `data.bufferBeforeUnit` | string | Unit of the buffer before: hour or day; null if not applicable. `hour`, `day` | | `data.bufferAfter` | number | Buffer time reserved after the rental; null if not applicable. | | `data.bufferAfterUnit` | string | Unit of the buffer after: hour or day; null if not applicable. `hour`, `day` | | `data.physicalProperties` | object | Physical properties (weight and dimensions); null if not recorded. | | `data.physicalProperties.weight` | number | Item weight in kilograms; null if not recorded. | | `data.physicalProperties.width` | number | Item width in centimeters; null if not recorded. | | `data.physicalProperties.height` | number | Item height in centimeters; null if not recorded. | | `data.physicalProperties.length` | number | Item length in centimeters; null if not recorded. | | `data.physicalProperties.volume` | number | Item volume in cubic meters (m³); null if not recorded. | | `data.physicalProperties.current` | number | Current draw in amperes; null if not recorded. | | `data.physicalProperties.power` | number | Power in watts; null if not recorded. | | `data.variants` | object[] | Item variants (empty if the item is of type fixed). | | `data.variants.variantId` | string | Unique identifier of the variant. | | `data.variants.variantName` | string | Variant name. | | `data.variants.variantPrice` | string | Rental price of the variant as a decimal string "1234.50" (ROUND_HALF_UP). | | `data.variants.salePrice` | string | Sale price of the variant as a decimal string "1234.50" (ROUND_HALF_UP); null if it has none. | | `data.variants.ean` | string | EAN/barcode of the variant; null if not recorded. | | `data.tags` | object[] | Tags associated with the item. | | `data.tags.id` | string | Unique identifier of the tag. | | `data.tags.name` | string | Tag name. | | `data.customFields` | object | Custom field values by custom field identifier; the definitions are in `/api/v1/custom-fields`. | | `data.createdAt` | string | Creation date in ISO 8601 with offset. | | `data.updatedAt` | string | Last update date in ISO 8601 with offset. | | `data.replacementValue` | string | Replacement value of the item as a decimal string "1234.50" (ROUND_HALF_UP); null if not recorded. | | `data.accessoryIds` | string[] | Identifiers of the items configured as accessories of this one. | | `data.alternativeIds` | string[] | Identifiers of the items configured as alternatives of this one. | | `meta` | object | Additional information about the response. | | `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. | | `meta.warnings.code` | string | Stable warning code. `deprecated` | | `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. | | `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. | | `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. | | `meta.warnings.link` | string | Where the deprecation is documented (the changelog). | *Example response · 200* ```json { "data": { "id": "item_9f3a2b", "name": "Example item", "sku": "CAM-FX6-01", "description": "Example text.", "orderInfo": "Example order info", "ean": "0000000000000", "itemType": "fixed", "stockCalculationMethod": "bulk", "collectionId": "collection_9f3a2b", "collectionName": "Example collection name", "images": [ "Example images" ], "salePrice": "120.00", "depositValue": "120.00", "minStock": 1, "serializedItemsCount": 1, "pricingSettings": { "type": "periodPrice", "price": "120.00", "period": "hour" }, "insuranceEnabled": true, "discountEnabled": true, "bufferBefore": 1, "bufferBeforeUnit": "hour", "bufferAfter": 1, "bufferAfterUnit": "hour", "physicalProperties": { "weight": 1, "width": 1, "height": 1, "length": 1, "volume": 1, "current": 1, "power": 1 }, "variants": [ { "variantId": "variant_9f3a2b", "variantName": "Example variant name", "variantPrice": "120.00", "salePrice": "120.00", "ean": "0000000000000" } ], "tags": [ { "id": "tag_9f3a2b", "name": "Example tag" } ], "customFields": { "example": "example" }, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-09-01T08:00:00.000Z", "replacementValue": "120.00", "accessoryIds": [ "accessory_9f3a2b" ], "alternativeIds": [ "alternative_9f3a2b" ] } } ``` ## Errors | Status | Codes | Meaning | | --- | --- | --- | | 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. | | 404 | `not_found` | It does not exist or is outside the scope of the API key. | | 409 | `conflict` | The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation. | | 412 | `precondition_failed` | The `If-Match` entity tag does not match the current representation. Read the resource again and retry. | | 422 | `idempotency_key_reused` | The same key was used before with a different body. Change the key. | ## Deprecation This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. --- Canonical URL: https://docs.filmo.io/rest-api/endpoint-reference/items/update-the-accessories-of-an-item Last updated: 2026-10-25