Skip to main content

Product scopes — Global, channel and channel × language

Every scoped product value lives at one of three levels:

  • Global — one value for every sales channel and every language;
  • Channel — one value for one sales channel, in every language that channel offers;
  • Channel × language — one value for one sales channel in one of its languages.

There is no language-only level. A translation is a Channel × language value, or a Channel value when the channel sells in one language. A value is resolved from the narrowest level that holds one: Channel × language → Channel → Global.

Which fields live where​

FieldGlobalChannelChannel × language
Name, descriptionyesyesyes
Text attributes marked scopableyesyesyes
Other scopable attributes (numbers, selects, booleans)yesyes—
Attributes not marked scopableyes——
Statusyesyesyes
Publication window, audience, minimum order quantity, returnableyesyes—
URL keyyesyesyes
Gallery alt text, hide image, gallery rolesyesyesyes
Attachment name, description, hiddenyesyesyes
Packaging-unit nameyesyesyes
SEO title, description, Open Graph fields (owned by the seo module)yesyesyes

SKU, type, attribute set, categories, stock settings and the download file have one value for the whole product and are edited at Global only. Writing one of them at another scope is refused with GLOBAL_ONLY_FIELD; writing a field at a level it does not support is refused with FIELD_NOT_AT_SCOPE.

Inherit, a value, or deliberately empty​

At Channel and Channel × language each field is in one of three states:

  • Inherits — the editor shows "Use value from parent scope" and the effective value comes from the level above;
  • Own value — the value stored at this scope;
  • Deliberately empty — an override that is empty on purpose. It stops the chain: a description emptied for one channel stays empty there even though Global has one. A required field (the name, a required attribute) cannot be emptied.

The write encoding​

Every writer — the editor's save, the import files and the PIM connector port — uses one encoding:

IntentJSONCSV cell
No changethe field absent, or ""an empty cell
Deliberately emptynullNULL (the whole cell)
Remove the own value and inherit{ "inherit": true }INHERIT (the whole cell)
A valuethe valuethe text; \NULL and \INHERIT are the literal words

This is not JSON Merge Patch, where null removes a member: here null stores an empty override and only { "inherit": true } removes one. It is also not Magento's __EMPTY__VALUE__ marker. INHERIT at Global and an empty required field are refused with SCOPED_VALUE_INVALID.

Reading and saving a scope​

  • GET /api/v1/admin/catalog/products/:id/scoped-values?channelId=&languageCode= (catalog:read) answers every field's effective value at the scope, its source (set, set_empty, inherited_channel, inherited_global, absent), the levels it supports, what the completeness check misses at that scope and the product's version.
  • PUT /api/v1/admin/catalog/products/:id/scoped-values (catalog:write) saves one scope in one Command with one audit entry. The body carries the version the editor read; a save made against an older version is refused with 409 VERSION_CONFLICT, so two operators never overwrite each other silently.
  • POST …/scoped-values/copy copies one Channel × language value to other channels of the product.

Channels a product leaves​

A value stored for a channel the product is no longer sold on, or for a language the channel no longer offers, is kept but ignored. The scope map lists such rows so they can be removed; they come back into effect if the product returns to that channel or language.

Duplicating a product​

Duplicate copies the product's values at every scope — Global, Channel and Channel × language, deliberately empty values and inherit states included — for every field family above, in one audited Command. Two things are not copied: URL keys (the copy gets a fresh Global key, because a key is one product's per channel) and status (the copy starts inactive everywhere, so it is reviewed before it is sold).