Assets

An asset is the catalog's record of a piece of media. The bytes live in Storage; the asset row says what the file is, which class of media it belongs to, and which product attribute may reference it.

Asset families

A family is a class of media with one shared shape — packshots, datasheets, installation videos.

{
  "code": "packshots",
  "labels": { "en": "Packshots", "de": "Produktfotos" },
  "naming_convention": {
    "source": "sku",
    "pattern": "{sku}_{index}",
    "allowed_extensions": ["jpg", "png", "webp"]
  }
}

Label keys follow the tenant's locale policy: de and en in a tenant that keeps text per language, as in these examples, de-DE and en-GB in one that keeps text per region. See Languages and locale codes.

naming_convention records how a file of this family is meant to be named: source is the product value the name is built from, pattern how it is assembled, allowed_extensions what may be uploaded. It is stored and not applied yet: nothing reads it, so it does not bind files to products or restrict uploads.

Like a reference entity, an asset family carries its own attributes — declare them with entity_type: "asset" and entity_ref: "<family code>".

Read, change or delete one family

Those assets do not go to the trash and cannot be restored. To retire a family and keep its assets, set its active to false instead.

On PUT, a body that names no column answers 400, and so does an active that is not true or false (invalid_active). A locale key in labels or descriptions that is not one of the tenant's write keys answers 422. An unknown id answers 404, and so does another tenant's id.

Assets

{
  "asset_family_id": "…",
  "code": "ACME-4711-BLK_1",
  "source": "storage",
  "storage_asset_id": "ast_01hxyz…",
  "attribute_values": { "common": { "alt_text": "Cordless drill, front" } }
}

{
  "asset_family_id": "…",
  "code": "ACME-4711-BLK_video",
  "source": "external",
  "external_url": "https://cdn.example.com/acme/4711/assembly.mp4"
}

The database enforces the pair, so neither half of a source/identifier combination can be stored on its own.

Rights and licence

Seven optional fields record who holds the rights to an asset and on what terms it may be used. Send them on create (POST /v1/products/assets) or update (PUT /v1/products/assets/{id}); they come back on reads. Each one is nullable, and each is also an exact-match filter on GET /v1/products/assets: a date filter matches one day, and there is no range filter, so ?license_valid_until=2026-12-31 finds the assets whose licence ends on that day, not the ones ending before it.

The fields are recorded, not enforced. The API does not check that license_valid_from comes before license_valid_until, and an asset past its last day is not hidden or flagged: showing the credit line and acting on an expiry is up to the client.

Two rules worth internalising

Never join on delivery_path. It is the convenient value for rendering and it changes when the file is moved. storage_asset_id survives a rename or a folder move, which is exactly why it and not the path is the identifier.

External URLs are gated, and only here. source: "external" is accepted only when the tenant has allow_external_media on and the host is on its external_media_allowed_hosts list. POST /v1/products/assets is the only place an external URL can enter the catalog, so it is the only place those checks exist.

Getting the bytes there

Uploading a file is a Storage operation, not a catalog one. Upload first, take the returned ast_… id, then create the asset row that points at it. See Storage for the upload paths. Manage product images and documents walks the whole job; an import does not carry media.

Where a product references it

A media or media-collection attribute stores the asset code:

{ "common": { "images": ["ACME-4711-BLK_1", "ACME-4711-BLK_2"] } }

Which attribute carries the main image is a family setting — families.image_attribute, read by grid thumbnails and pickers. See Data model.

Read, change or delete one asset

The first DELETE only moves the asset to the trash, and its stored file stays where it is. The second DELETE, or emptying the trash, deletes the asset for good and removes the stored file first, through the storage service, unless another asset uses the same file. An asset with no stored file (an external URL) deletes without one.

Nothing in the catalog blocks deleting an asset for good: products, categories and manufacturers that name it keep their reference, and the answer counts them as warnings. When storage does not answer, the delete for good is refused with 409 (storage_unreachable) and the asset stays in the trash. An id no asset of this tenant carries answers 404.

Trash and restore

The shared rules for the trash, including emptying it and the daily purge, are on Trash.

Deleting an asset sends it to the trash. A second delete of the same asset deletes it for good, and so does emptying the trash. The platform also deletes trashed records that outlive the tenant's trash retention (90 days unless the tenant set another), except one that something still blocks.

The first delete fires asset.trashed and a restore asset.restored. asset.deleted fires only once the record is deleted for good. See Deletes and the trash.

• Restore. POST /v1/products/assets/{id}/restore brings the asset back from the trash. Nothing else goes to the trash with an asset, so nothing else comes back with it. Everything that pointed at the asset acts again as it did, because nothing was changed when it went. Restoring needs the same right as deleting. The answer lists every record that came back in restored.
• Refused with 409. not_in_trash when the asset is not in the trash. parent_in_trash when the record it belongs to is in the trash in another group; details.restore names the call that brings that one back first.
• Refused with 404 when no asset of this tenant has that id. An asset of another tenant gets the same 404, not a 403.
• Empty the trash. POST /v1/products/assets/trash/empty deletes the trashed assets for good, oldest first, up to 200 per call, each through the same checks as a second DELETE.
• A record a blocker holds is listed in blocked with its reason and stays in the trash; the rest of the call goes on.
• deleted lists what this call removed for good. more: true means the call stopped at its limit and the trash may hold more: call it again.
• A storefront contact gets 403: emptying the trash is back-office work.

GET /v1/products/assets also filters on the four file fields in the table above, each as an exact match.

GET /v1/products/asset_families also filters on active. active is true unless the entry is inactive (false). A list returns both unless you filter, so use ?active=true for a picker. Records that already carry an inactive entry keep it; a write cannot newly assign one (409 entry_inactive). active is also an optional boolean on POST and PUT of an asset family, default true: send false to make it inactive, and anything that is not a boolean answers 400 invalid_active.

Reading and filtering the trash. GET /v1/products/assets leaves trashed assets out unless the call asks with trashed: only returns the trash alone, include returns the live and the trashed assets together. Each asset carries the fields below, and each one is also an exact-match filter on the list call.

The platform sets these fields when an asset is deleted and clears them when it is restored, never through an update, so a client does not normally send them in a write.

Where to go next

• Storage — where the bytes actually live.
• Data model — declaring the media attribute.
• Import and export — binding files to products in bulk.