From cc4aefd4f4d4319ce674cfc9d19f44ee17129c59 Mon Sep 17 00:00:00 2001 From: soumah Date: Mon, 6 Apr 2026 17:23:29 -0500 Subject: [PATCH 1/4] ACP2E-4454: [Documentation] Update devdocs how to keep inheritance of product gallery in REST API when updating a product in store view level. --- src/data/navigation/sections/rest.js | 4 + src/pages/rest/tutorials/image/index.md | 4 + .../image/product-image-store-scope.md | 433 ++++++++++++++++++ 3 files changed, 441 insertions(+) create mode 100644 src/pages/rest/tutorials/image/product-image-store-scope.md diff --git a/src/data/navigation/sections/rest.js b/src/data/navigation/sections/rest.js index 9353c3fff..26db5b3bb 100644 --- a/src/data/navigation/sections/rest.js +++ b/src/data/navigation/sections/rest.js @@ -459,6 +459,10 @@ module.exports = [ title: "Step 4. Delete an image of a product", path: "/rest/tutorials/image/delete.md", }, + { + title: "Manage product images at the store view level", + path: "/rest/tutorials/image/product-image-store-scope.md", + }, ], }, ], diff --git a/src/pages/rest/tutorials/image/index.md b/src/pages/rest/tutorials/image/index.md index f934b7694..340b15b57 100644 --- a/src/pages/rest/tutorials/image/index.md +++ b/src/pages/rest/tutorials/image/index.md @@ -19,6 +19,10 @@ This tutorial demonstrates how to use the Adobe Commerce REST APIs to: 1. [Delete an image](delete.md) + + +For multi-store environments, see [Manage product images at the store view level](product-image-store-scope.md) for how `media_gallery_entries` behaves across store views and how to restore inherited field values. + This **4-step tutorial** generally takes **30 minutes**. ## Before you begin diff --git a/src/pages/rest/tutorials/image/product-image-store-scope.md b/src/pages/rest/tutorials/image/product-image-store-scope.md new file mode 100644 index 000000000..a4322d28e --- /dev/null +++ b/src/pages/rest/tutorials/image/product-image-store-scope.md @@ -0,0 +1,433 @@ +--- +title: Manage product images at the store view level +description: Learn how to use the Adobe Commerce REST API to preserve, override, and restore product image gallery settings per store view in a multi-store setup. +keywords: + - REST + - product images + - store view + - multi-store + - media gallery +--- + +# Manage product images at the store view level + +This page explains how product image gallery inheritance works in a multi-store Adobe Commerce setup and how to control it using the REST API. These behaviours only apply when your installation has multiple store views. In a single-store setup, all requests target the global scope and inheritance does not apply. + +If you are new to the product media API, complete the [Add and manage product images tutorial](/rest/tutorials/image/) first. + +## Before you begin + +* An Adobe Commerce instance with at least two store views configured. The examples use `default` and a second store view. See [Add a store view](https://experienceleague.adobe.com/docs/commerce-admin/stores-sales/site-store/store-views.html) in the Admin documentation. + +* A product with images in all store views, where images currently use the default value (the **Use Default Value** checkbox is enabled in Admin) in each store view. + +* An admin access token. See [Generate an admin token](../../../get-started/authentication/gs-authentication-token.md). + +* A REST client, such as Postman. + +## Preserve images during a product update + +When you update a product at the store view level, you can control whether the request affects the product's media gallery. + +### Omit media_gallery_entries + +If the `media_gallery_entries` field is not present in the payload, no changes are made to the product images in that scope. All store views continue to use the default value. + +**Endpoint:** + +```html +POST http://domain.com/rest/default/V1/products +``` + + + +#### Payload + +```json +{ + "product": { + "sku": "MJ03", + "name": "product name override in default store view" + } +} +``` + +#### Response + +```json +{ + "sku": "MJ03", + "name": "product name override in default store view", + "media_gallery_entries": [ + { + "id": 709, + "media_type": "image", + "label": "", + "position": 1, + "disabled": false, + "types": [ + "image", + "small_image", + "thumbnail" + ], + "file": "\/m\/j\/mj03-black_main_12.jpg" + }, + { + "id": 710, + "media_type": "image", + "label": "", + "position": 2, + "disabled": false, + "types": [], + "file": "\/m\/j\/mj03-black_alt1_12.jpg" + }, + { + "id": 711, + "media_type": "image", + "label": "", + "position": 3, + "disabled": false, + "types": [], + "file": "\/m\/j\/mj03-black_back_12.jpg" + } + ] +} +``` + +After this call, images in each store view continue to use the **Use Default Value** setting. + +### Set media_gallery_entries to null + +Explicitly setting `media_gallery_entries` to `null` has the same effect as omitting the field — the product's existing media gallery is left unchanged. + +**Endpoint:** + +```html +POST http://domain.com/rest/default/V1/products +``` + + + +#### Payload + +```json +{ + "product": { + "sku": "MJ03", + "name": "product name override in default store view", + "media_gallery_entries": null + } +} +``` + +#### Response + +```json +{ + "sku": "MJ03", + "name": "product name override in default store view", + "media_gallery_entries": [ + { + "id": 709, + "media_type": "image", + "label": "", + "position": 1, + "disabled": false, + "types": [ + "image", + "small_image", + "thumbnail" + ], + "file": "\/m\/j\/mj03-black_main_12.jpg" + }, + { + "id": 710, + "media_type": "image", + "label": "", + "position": 2, + "disabled": false, + "types": [], + "file": "\/m\/j\/mj03-black_alt1_12.jpg" + }, + { + "id": 711, + "media_type": "image", + "label": "", + "position": 3, + "disabled": false, + "types": [], + "file": "\/m\/j\/mj03-black_back_12.jpg" + } + ] +} +``` + + + +Setting `media_gallery_entries` to `null` and omitting the field are equivalent. Neither modifies the images currently configured for any store view. + + + +Setting `media_gallery_entries` to an empty array `[]` is **not** the same as `null`. An empty array is treated as an explicit instruction to remove all gallery entries from all store views. Always use `null` or omit the field when you do not intend to modify images. + +## Override store view image fields + +When you retrieve a product and POST it back with the `media_gallery_entries` array populated, the store view fields are explicitly set — overriding any inherited values. + +**Step 1.** Retrieve the full product data from the store view you want to update. + +**Endpoint:** + +```html +GET http://domain.com/rest/default/V1/products/MJ03 +``` + +**Step 2.** Use the `media_gallery_entries` from the GET response in an update call. + +**Endpoint:** + +```html +POST http://domain.com/rest/default/V1/products +``` + +After this call: + +* In the **default store view**: image sort order, label, visibility, and roles are no longer using the default value (**Use Default Value** is unchecked). + +* In the **second store view**: image fields continue to use the default value (unaffected). + +## Restore inheritance by setting fields to null + +Setting individual image fields to `null` restores the **Use Default Value** state for those fields — equivalent to re-enabling the **Use Default Value** checkbox in the Admin product editor. + +The following fields support `null` to restore inheritance: + +| Field | Effect of `null` | +|---|---| +| `label` | Reverts to the global alt text | +| `position` | Reverts to the global display order | +| `disabled` | Reverts to the global visibility setting | +| `extension_attributes.video_content.video_title` | Reverts to the global video title (video entries only) | +| `extension_attributes.video_content.video_description` | Reverts to the global video description (video entries only) | + +**Endpoint:** + +```html +POST http://domain.com/rest/default/V1/products +``` + + + +#### Payload + +```json +{ + "product": { + "sku": "MJ03", + "media_gallery_entries": [ + { + "id": 709, + "media_type": "image", + "label": null, + "position": null, + "disabled": null, + "types": [ + "image", + "small_image", + "thumbnail" + ], + "file": "\/m\/j\/mj03-black_main_12.jpg" + }, + { + "id": 710, + "media_type": "image", + "label": null, + "position": null, + "disabled": null, + "types": [], + "file": "\/m\/j\/mj03-black_alt1_12.jpg" + }, + { + "id": 711, + "media_type": "image", + "label": null, + "position": null, + "disabled": null, + "types": [], + "file": "\/m\/j\/mj03-black_back_12.jpg" + } + ] + } +} +``` + +#### Response + +```json +{ + "sku": "MJ03", + "name": "product name override in default store view", + "media_gallery_entries": [ + { + "id": 709, + "media_type": "image", + "label": "", + "position": 1, + "disabled": false, + "types": [ + "image", + "small_image", + "thumbnail" + ], + "file": "\/m\/j\/mj03-black_main_12.jpg" + }, + { + "id": 710, + "media_type": "image", + "label": "", + "position": 2, + "disabled": false, + "types": [], + "file": "\/m\/j\/mj03-black_alt1_12.jpg" + }, + { + "id": 711, + "media_type": "image", + "label": "", + "position": 3, + "disabled": false, + "types": [], + "file": "\/m\/j\/mj03-black_back_12.jpg" + } + ] +} +``` + +After this call, the **Use Default Value** checkbox is re-enabled for all specified fields in each store view. + +## Add a new image at the store view level + +When you add a new image using the media endpoint, it becomes visible in all store views. + +**Endpoint:** + +```html +POST http://domain.com/rest/default/V1/products/MJ03/media +``` + + + +#### Payload + +```json +{ + "entry": { + "media_type": "image", + "label": "New image label", + "position": 4, + "disabled": false, + "content": { + "base64_encoded_data": "", + "type": "image/png", + "name": "new-image.png" + }, + "types": [] + } +} +``` + +#### Response + +```json +3434 +``` + +The response returns the new image `id`. + +After this call: + +* The new image is visible in all store views. + +* In the **default store view**: Images sort order is no longer using the default value. The new image's `label` and `disabled` are not inheriting. + +* In the **second store view**: all image fields continue to use the default value. + +## Update a media entry at the store view level + +To update a specific image, first retrieve its current data, then send an update. + +**Step 1.** Retrieve the image entry. + +**Endpoint:** + +```html +GET http://domain.com/rest/default/V1/products/MJ03/media/3434 +``` + +**Step 2.** Update the entry with the modified fields. + +**Endpoint:** + +```html +PUT http://domain.com/rest/default/V1/products/MJ03/media/3434 +``` + + + +#### Payload + +```json +{ + "entry": { + "id": 3434, + "media_type": "image", + "label": "Updated label for default store view", + "position": 4, + "disabled": false, + "types": [], + "file": "\/n\/e\/new-image.png" + } +} +``` + +#### Response + +```json +true +``` + +After this call: + +* The image is updated in the **default store view**. +* In the **default store view**: Images sort order continues to not use the default value. +* The **second store view** continues to use the default value (unaffected). + +## Delete a media entry + +Deleting an image entry removes it from the product across all store views. + +**Endpoint:** + +```html +DELETE http://domain.com/rest/default/V1/products/MJ03/media/3434 +``` + +**Response:** + +```json +true +``` + +After this call: + +* The image is deleted from **all store views** +* In the **default store view**: Existing images sort order will go back to using default value. +* The **second store view** continues to use the default value (unaffected). + +## Related resources + +* [Add and manage product images tutorial](/rest/tutorials/image/) + +* [Step 2. Add a new image](new.md) + +* [Step 3. Update an image](update.md) From b7de0a61ef945d90faad9b67e5ed6e4add84ea38 Mon Sep 17 00:00:00 2001 From: soumah Date: Mon, 6 Apr 2026 18:01:05 -0500 Subject: [PATCH 2/4] ACP2E-4454: [Documentation] Update devdocs how to keep inheritance of product gallery in REST API when updating a product in store view level. - Fix test failures --- src/pages/rest/tutorials/image/product-image-store-scope.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/pages/rest/tutorials/image/product-image-store-scope.md b/src/pages/rest/tutorials/image/product-image-store-scope.md index a4322d28e..b209f2aa9 100644 --- a/src/pages/rest/tutorials/image/product-image-store-scope.md +++ b/src/pages/rest/tutorials/image/product-image-store-scope.md @@ -3,10 +3,6 @@ title: Manage product images at the store view level description: Learn how to use the Adobe Commerce REST API to preserve, override, and restore product image gallery settings per store view in a multi-store setup. keywords: - REST - - product images - - store view - - multi-store - - media gallery --- # Manage product images at the store view level From bb559b39d5c1fd15c932fbae04fe92e249fef4ea Mon Sep 17 00:00:00 2001 From: bubasuma Date: Thu, 9 Apr 2026 14:56:54 -0500 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Kevin Harper Co-authored-by: bubasuma --- .../image/product-image-store-scope.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/src/pages/rest/tutorials/image/product-image-store-scope.md b/src/pages/rest/tutorials/image/product-image-store-scope.md index b209f2aa9..9f6e73968 100644 --- a/src/pages/rest/tutorials/image/product-image-store-scope.md +++ b/src/pages/rest/tutorials/image/product-image-store-scope.md @@ -7,7 +7,7 @@ keywords: # Manage product images at the store view level -This page explains how product image gallery inheritance works in a multi-store Adobe Commerce setup and how to control it using the REST API. These behaviours only apply when your installation has multiple store views. In a single-store setup, all requests target the global scope and inheritance does not apply. +This topic explains how product image gallery inheritance works in a multi-store Adobe Commerce setup and how to control it using the REST API. These behaviours only apply when your installation has multiple store views. In a single-store setup, all requests target the global scope and inheritance does not apply. If you are new to the product media API, complete the [Add and manage product images tutorial](/rest/tutorials/image/) first. @@ -90,11 +90,15 @@ POST http://domain.com/rest/default/V1/products } ``` -After this call, images in each store view continue to use the **Use Default Value** setting. +After this call, images in each store view continue to implement the **Use Default Value** setting. ### Set media_gallery_entries to null -Explicitly setting `media_gallery_entries` to `null` has the same effect as omitting the field — the product's existing media gallery is left unchanged. +Setting `media_gallery_entries` to `null` and omitting the field are equivalent. Neither modifies the images currently configured for any store view. + + + +Setting `media_gallery_entries` to an empty array `[]` is **not** the same as `null`. An empty array is treated as an explicit instruction to remove all gallery entries from all store views. Always use `null` or omit the field when you do not intend to modify images. **Endpoint:** @@ -158,13 +162,6 @@ POST http://domain.com/rest/default/V1/products } ``` - - -Setting `media_gallery_entries` to `null` and omitting the field are equivalent. Neither modifies the images currently configured for any store view. - - - -Setting `media_gallery_entries` to an empty array `[]` is **not** the same as `null`. An empty array is treated as an explicit instruction to remove all gallery entries from all store views. Always use `null` or omit the field when you do not intend to modify images. ## Override store view image fields @@ -194,7 +191,7 @@ After this call: ## Restore inheritance by setting fields to null -Setting individual image fields to `null` restores the **Use Default Value** state for those fields — equivalent to re-enabling the **Use Default Value** checkbox in the Admin product editor. +Setting individual image fields to `null` restores the **Use Default Value** state for those fields. This is the equivalent of re-enabling the **Use Default Value** checkbox in the Admin product editor. The following fields support `null` to restore inheritance: From d3774a1f6e84fa53b4f4cd4a7fd6a9890c16efd0 Mon Sep 17 00:00:00 2001 From: soumah Date: Thu, 9 Apr 2026 15:06:10 -0500 Subject: [PATCH 4/4] Apply suggestions from code review --- .../rest/tutorials/image/product-image-store-scope.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/pages/rest/tutorials/image/product-image-store-scope.md b/src/pages/rest/tutorials/image/product-image-store-scope.md index 9f6e73968..ff2a131b8 100644 --- a/src/pages/rest/tutorials/image/product-image-store-scope.md +++ b/src/pages/rest/tutorials/image/product-image-store-scope.md @@ -7,7 +7,7 @@ keywords: # Manage product images at the store view level -This topic explains how product image gallery inheritance works in a multi-store Adobe Commerce setup and how to control it using the REST API. These behaviours only apply when your installation has multiple store views. In a single-store setup, all requests target the global scope and inheritance does not apply. +This topic explains how product image gallery inheritance works in a multi-store Adobe Commerce setup and how to control it using the REST API. These behaviours only apply when your installation has multiple store views. In a single-store setup, all requests target the global scope and inheritance does not apply. If you are new to the product media API, complete the [Add and manage product images tutorial](/rest/tutorials/image/) first. @@ -90,7 +90,7 @@ POST http://domain.com/rest/default/V1/products } ``` -After this call, images in each store view continue to implement the **Use Default Value** setting. +After this call, images in each store view continue to implement the **Use Default Value** setting. ### Set media_gallery_entries to null @@ -162,7 +162,6 @@ POST http://domain.com/rest/default/V1/products } ``` - ## Override store view image fields When you retrieve a product and POST it back with the `media_gallery_entries` array populated, the store view fields are explicitly set — overriding any inherited values. @@ -191,7 +190,7 @@ After this call: ## Restore inheritance by setting fields to null -Setting individual image fields to `null` restores the **Use Default Value** state for those fields. This is the equivalent of re-enabling the **Use Default Value** checkbox in the Admin product editor. +Setting individual image fields to `null` restores the **Use Default Value** state for those fields. This is the equivalent of re-enabling the **Use Default Value** checkbox in the Admin product editor. The following fields support `null` to restore inheritance: