Items

Update an item

Updates the catalog metadata of an item (send only the fields to change).

PATCH

/api/v1/items/{itemId}

curl https://app.filmo.io/api/v1/items/item_8f2a1c \
  --request PATCH \
  --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 '{
  "name": "Sony FX6 (cuerpo)",
  "description": "Cámara de cine digital full-frame, montura E.",
  "synonyms": [
    "FX6",
    "Sony cine full frame"
  ],
  "tags": [
    "Cámaras",
    "Cine"
  ]
}'

Node.jsfetch('https://app.filmo.io/api/v1/items/item_8f2a1c', { method: 'PATCH', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Sony FX6 (cuerpo)', description: 'Cámara de cine digital full-frame, montura E.', synonyms: ['FX6', 'Sony cine full frame'], tags: ['Cámaras', 'Cine'] }) })Pythonimport uuid import requests requests.patch( "https://app.filmo.io/api/v1/items/item_8f2a1c", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "name": "Sony FX6 (cuerpo)", "description": "Cámara de cine digital full-frame, montura E.", "synonyms": [ "FX6", "Sony cine full frame" ], "tags": [ "Cámaras", "Cine" ] } )

{
  "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"
    ]
  }
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "items:write"
}

{
  "type": "https://docs.filmo.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Resource not found",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The current state of the resource does not allow the operation",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "",
      "code": "invalid_state",
      "message": "The current state of the resource does not allow the operation"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/precondition_failed",
  "title": "Precondition failed",
  "status": 412,
  "code": "precondition_failed",
  "detail": "The resource changed since you read it: read it again and retry",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/idempotency_key_reused",
  "title": "Idempotency-Key reused",
  "status": 422,
  "code": "idempotency_key_reused",
  "detail": "The Idempotency-Key header was already used with a different body",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

synonyms and tags replace the whole list. The stock method and the item type can NOT be changed here: they are destructive once there is stock or variants, and are set on create. Returns the updated item in detail.

Authorizations

Bearer API key with the scope below. items:write

Headers

Idempotency-Keystring

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.

Limits: min length 1, max length 255

Example:"9f1c2f4e-3a5b-4f6d-8e7a-0b1c2d3e4f5a"

If-Matchstring

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.

Example:"\"3sT3d9pBvZq4h2N0w8x1YkLmQ7c\""

Path parameters

itemIdstringRequired

Item identifier.

Limits: min length 1

Body

application/json

Body schema: ItemUpdateBody

namestring

Item name.

Limits: min length 1

descriptionstring | null

Item description; null clears it.

skustring | null

SKU reference. Unique within the account; null clears it.

Limits: min length 1

collectionIdstring | null

Collection it belongs to; null removes it from any collection.

Limits: min length 1

orderInfostring | null

Order information: preparation or delivery notes that do reach the customer; null clears it.

synonymsstring[]

Synonyms by which the item should be found in the search. Replaces the entire list.

tagsstring[]

Tags, by identifier or by name; a name that does not exist creates the tag. Replaces the entire list.

Limits: max 50 items, each min length 1, each max length 100

Response

application/json

Successful response.

Response schema: ItemDetailDto

Envelope: ItemDetailResponse. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay

dataobject

The item in full, as returned by the API.

Show child attributes

data.idstring

Unique identifier of the item.

data.namestring

Item name.

data.skustring | null

SKU reference of the item; null if not recorded.

data.descriptionstring | null

Item description; null if not recorded.

data.orderInfostring | null

Additional information for the order (preparation/delivery notes); null if not recorded.

data.eanstring | null

EAN/barcode; null if not recorded.

data.itemTypestring

Item type: fixed (simple item) or variant (item with variants).

Available options: fixed, variant

data.stockCalculationMethodstring

Stock calculation method: bulk (in bulk, by quantity) or serialized (by serialized items).

Available options: bulk, serialized

data.collectionIdstring | null

Identifier of the collection it belongs to; null if it is in none.

data.collectionNamestring | null

Name of the collection it belongs to; null if it is in none.

data.imagesstring[]

URLs of the item images.

data.salePricestring | null

Sale price as a decimal string "1234.50" (ROUND_HALF_UP); null if it has none.

Limits: pattern ^-?\d+\.\d{2}$

data.depositValuestring | null

Deposit amount as a decimal string "1234.50" (ROUND_HALF_UP); null if it has none.

Limits: pattern ^-?\d+\.\d{2}$

data.minStocknumber | null

Minimum stock configured for alerts; null if not configured.

data.serializedItemsCountnumber

Number of serialized items registered for the item.

data.pricingSettingsobject | null

Rental pricing configuration; null if not configured.

Show child attributes

data.pricingSettings.typestring | null

Pricing mode: periodPrice (price per period), fixedPrice (fixed price) or pricingStructure (pricing structure); null if the item has none configured.

Available options: periodPrice, fixedPrice, pricingStructure

data.pricingSettings.pricestring | null

Base rental price as a decimal string "1234.50" (ROUND_HALF_UP); null if not applicable.

Limits: pattern ^-?\d+\.\d{2}$

data.pricingSettings.periodstring | null

Period unit of the price: hour, day, week or month; null if the item has none configured.

Available options: hour, day, week, month

data.insuranceEnabledboolean

Whether the item allows insurance.

data.discountEnabledboolean

Whether the item allows discounts.

data.bufferBeforenumber | null

Buffer time reserved before the rental; null if not applicable.

data.bufferBeforeUnitstring | null

Unit of the buffer before: hour or day; null if not applicable.

Available options: hour, day

data.bufferAfternumber | null

Buffer time reserved after the rental; null if not applicable.

data.bufferAfterUnitstring | null

Unit of the buffer after: hour or day; null if not applicable.

Available options: hour, day

data.physicalPropertiesobject | null

Physical properties (weight and dimensions); null if not recorded.

Show child attributes

data.physicalProperties.weightnumber | null

Item weight in kilograms; null if not recorded.

data.physicalProperties.widthnumber | null

Item width in centimeters; null if not recorded.

data.physicalProperties.heightnumber | null

Item height in centimeters; null if not recorded.

data.physicalProperties.lengthnumber | null

Item length in centimeters; null if not recorded.

data.physicalProperties.volumenumber | null

Item volume in cubic meters (m³); null if not recorded.

data.physicalProperties.currentnumber | null

Current draw in amperes; null if not recorded.

data.physicalProperties.powernumber | null

Power in watts; null if not recorded.

data.variantsobject[]

Item variants (empty if the item is of type fixed).

Show child attributes

data.variants.variantIdstring

Unique identifier of the variant.

data.variants.variantNamestring

Variant name.

data.variants.variantPricestring

Rental price of the variant as a decimal string "1234.50" (ROUND_HALF_UP).

Limits: pattern ^-?\d+\.\d{2}$

data.variants.salePricestring | null

Sale price of the variant as a decimal string "1234.50" (ROUND_HALF_UP); null if it has none.

Limits: pattern ^-?\d+\.\d{2}$

data.variants.eanstring | null

EAN/barcode of the variant; null if not recorded.

data.tagsobject[]

Tags associated with the item.

Show child attributes

data.tags.idstring

Unique identifier of the tag.

data.tags.namestring

Tag name.

data.customFieldsobject<string, any>

Custom field values by custom field identifier; the definitions are in /api/v1/custom-fields.

data.createdAtstring<date-time>

Creation date in ISO 8601 with offset.

data.updatedAtstring<date-time>

Last update date in ISO 8601 with offset.

data.replacementValuestring | null

Replacement value of the item as a decimal string "1234.50" (ROUND_HALF_UP); null if not recorded.

Limits: pattern ^-?\d+\.\d{2}$

data.accessoryIdsstring[]

Identifiers of the items configured as accessories of this one.

data.alternativeIdsstring[]

Identifiers of the items configured as alternatives of this one.

metaobject

Additional information about the response.

Show child attributes

meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes

meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

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.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. Versioning policy

Catalog & inventory
Item
The item, as returned by the API.

Was this page helpful?

Request examples

Authorizations

Headers

Path parameters

Body

Response

Errors

Deprecation

Related

Related pages

Item