Product Images (Beta)

International Enhancements for Multi-Storefront

This feature is currently available for Enterprise stores and Partner Sandboxes. If the feature is not working as expected, please contact technical support, as the feature likely needs to be enabled for the individual store. To become an enterprise customer, contact your BigCommerce Customer Service Manager or our support team.
We may introduce changes to this beta feature without notice.

Using the Catalog features of the Admin API, you can set and query information for product images.

First, add an image to the product for the global store. You can do so using the Create a product image endpoint of the REST Management API.

By default, product images are visible on all storefront channels and locales. To change its visibility, see Product image visibility.

You can change the details of an image that you have added to a product:

Set product image information for the catalog. You can set global values and overrides for the image information in a channel locale.
Remove overrides for the product’s image in a channel locale. A channel then inherits global values.
Query product image information, those set at the global level and the overrides.

For a full schema, see the GraphQL Admin API reference.

Input fields

Setting or removing information requires that you specify ID fields in the input. For more information on how to specify ID fields, see Input fields.

Product image visibility

The addedToProduct field indicates the visibility of an image.

Add image visibility

The following example makes a product image visible in a channel locale. To set the image visibility for the global store, don’t include the context field in the input.

Request

Response

Example mutation: Add product image visibility to a channel locale

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 mutation ($input: AddImagesToProductInput!) {
7   product {
8     addImagesToProduct(input: $input) {
9       images {
10         edges {
11           node {
12             id
13 
14             # For the global store         
15             altText   
16             isThumbnail 
17             sortOrder  
18             urlStandard  
19             urlZoom
20             addedToProduct
21 
22             # For the channel locale
23             overrides (context: {channelId: "bc/store/channel/1", locale: "en"} ) {
24               edges {
25                 node {
26                   ... on ProductImagesOverridesForChannelLocale {
27                     context {
28                       channelId
29                       locale
30                     }
31                     altText
32                     sortOrder
33                     addedToProduct
34                   }
35                 }
36               }
37             }
38           }
39         }
40       }
41     }
42   }
43 }

GraphQL variables

1 {
2   "input": {
3       "productId": "bc/store/product/111",
4 
5       // For the channel locale
6       "context": {
7         "channelId": "bc/store/channel/1",
8         "locale": "en"
9       },
10       "ids": ["bc/store/productImage/371", "bc/store/productImage/372"]
11     }
12 }

Remove image visibility

The following example makes a product image not visible in a channel locale. To set the image visibility for the global store, don’t include the context field in the input.

Request

Response

Example mutation: Remove product image visibility from a channel locale

1 mutation ($input: RemoveImagesFromProductInput!) {
2   product {
3     removeImagesFromProduct(input: $input) {
4       images {
5         edges {
6           node {
7             id
8             altText
9             isThumbnail
10             sortOrder
11             urlStandard
12             urlZoom
13             addedToProduct
14             overrides(context: { channelId: "bc/store/channel/1", locale: "fr" }) {
15               edges {
16                 node {
17                   ... on ProductImagesOverridesForChannelLocale {
18                     context {
19                       channelId
20                       locale
21                     }
22                     altText
23                     sortOrder
24                     addedToProduct
25                   }
26                 }
27               }
28             }
29           }
30         }
31       }
32     }
33   }
34 }

GraphQL variables

1 {
2   "input": {
3     "productId": "bc/store/product/111",
4     "context": {
5       "channelId": "bc/store/channel/1",
6       "locale": "fr"
7     },
8     "ids": ["bc/store/productImage/371", "bc/store/productImage/372"]
9   }
10 }

Product image information

Set image information

The following example sets product image information for the global store and a channel locale.

Request

Response

Example mutation: Set global product image information

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 mutation ($input: UpdateProductImagePropertiesInput!) {
7   product {
8     updateProductImageProperties(input: $input) {
9       images {
10         edges {
11           node {
12             id         
13             altText  
14             isThumbnail  
15             sortOrder  
16             urlStandard 
17             urlZoom
18             addedToProduct    
19             overrides( context: {channelId: "bc/store/channel/1", locale: "en"}) {
20               edges {
21                 node {
22                   ... on ProductImagesOverridesForChannelLocale {
23                     context {
24                       channelId
25                       locale
26                     }
27                     sortOrder
28                     altText
29                     isThumbnail
30                     addedToProduct
31                   }
32                 }
33               }
34             }
35           }
36         }
37       }
38     }
39   }
40 }

GraphQL variables

1 {
2   "input": {
3     "productId": "bc/store/product/111",
4     "data": [
5       {
6         "imageId": "bc/store/productImage/371",
7         "sortOrder": 2, 
8         "altText": "Global alt text", 
9         "isThumbnail": true, 
10         "overrides": [
11           {
12             "channelLocaleOverrides": {
13               "context": {
14                 "channelId": "bc/store/channel/1", 
15                 "locale": "en"
16               },
17               "data": {
18                 "sortOrder": 1, 
19                 "altText": "Channel-specific alt text",
20                 "isThumbnail": true 
21               }
22             }
23           }
24         ]
25       },
26       {
27         "imageId": "bc/store/productImage/372", 
28         "sortOrder": 1, 
29         "altText": "Global alt text",
30         "isThumbnail": false
31       }
32     ]
33   }
34 }

Remove image information from a locale

The following example removes product image overrides for the channel locale.

Request

Response

Example mutation: Remove product image overrides for a locale

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 mutation removeProductImagePropertiesOverrides($input: RemoveProductImagePropertiesOverridesInput!) {
7   product {
8     removeProductImagePropertiesOverrides(input: $input) {
9       images {
10         edges {
11           node {            
12             id        
13             altText    
14             isThumbnail  
15             sortOrder  
16             urlStandard 
17             urlZoom
18             addedToProduct
19             overrides ( context: { channelId: "bc/store/channel/1", locale: "en"}) {
20               edges {
21                 node {
22                   ... on ProductImagesOverridesForChannelLocale {
23                     context {
24                       channelId
25                       locale
26                     }
27                     altText
28                     isThumbnail
29                     sortOrder
30                     addedToProduct
31                   }
32                 }
33               }
34             }
35           } 
36         }
37       }
38     }
39   }
40 }

GraphQL variables

1 {
2   "input": {
3     "productId": "bc/store/product/111",
4     "data": [
5       {
6         "imageId": "bc/store/productImage/371",
7         "contexts": [
8           {
9             "channelLocaleContext": {
10               "channelId": "bc/store/channel/1", 
11               "locale": "en"
12             }
13           }
14         ]
15       }
16     ]
17   }
18 }

Query image information

The following example retrieves product image information. You can retrieve global information for the store and overrides for the channel locale.

You can also use the imagesOverrides node to retrieve overrides. This node will return only the images with overrides in the specific channel locale.

Request

Response

Example query: Get product image information

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 query {
7   store {
8     product(id: "bc/store/product/111") {
9       images {
10         edges {
11           node {
12             id        
13             altText    
14             isThumbnail  
15             sortOrder  
16             urlStandard 
17             urlZoom
18             addedToProduct
19             overrides( context: {channelId: "bc/store/channel/1", locale: "en"}) {
20               edges {
21                 node {
22                   ... on ProductImagesOverridesForChannelLocale {
23                     context {
24                       channelId
25                       locale
26                     }
27                     altText
28                     isThumbnail
29                     sortOrder
30                     addedToProduct
31                   }
32                 }
33               }
34             }
35           }
36         }
37       }
38     }
39   }
40 }

International Enhancements for Multi-Storefront

This feature is currently available for Enterprise stores and Partner Sandboxes. If the feature is not working as expected, please contact technical support, as the feature likely needs to be enabled for the individual store. To become an enterprise customer, contact your BigCommerce Customer Service Manager or our support team.
We may introduce changes to this beta feature without notice.

Using the Catalog features of the Admin API, you can set and query information for product images.

First, add an image to the product for the global store. You can do so using the Create a product image endpoint of the REST Management API.

By default, product images are visible on all storefront channels and locales. To change its visibility, see Product image visibility.

You can change the details of an image that you have added to a product:

Set product image information for the catalog. You can set global values and overrides for the image information in a channel locale.
Remove overrides for the product’s image in a channel locale. A channel then inherits global values.
Query product image information, those set at the global level and the overrides.

For a full schema, see the GraphQL Admin API reference.

Input fields

Setting or removing information requires that you specify ID fields in the input. For more information on how to specify ID fields, see Input fields.

Product image visibility

The addedToProduct field indicates the visibility of an image.

Add image visibility

The following example makes a product image visible in a channel locale. To set the image visibility for the global store, don’t include the context field in the input.

Request

Response

Example mutation: Add product image visibility to a channel locale

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 mutation ($input: AddImagesToProductInput!) {
7   product {
8     addImagesToProduct(input: $input) {
9       images {
10         edges {
11           node {
12             id
13 
14             # For the global store         
15             altText   
16             isThumbnail 
17             sortOrder  
18             urlStandard  
19             urlZoom
20             addedToProduct
21 
22             # For the channel locale
23             overrides (context: {channelId: "bc/store/channel/1", locale: "en"} ) {
24               edges {
25                 node {
26                   ... on ProductImagesOverridesForChannelLocale {
27                     context {
28                       channelId
29                       locale
30                     }
31                     altText
32                     sortOrder
33                     addedToProduct
34                   }
35                 }
36               }
37             }
38           }
39         }
40       }
41     }
42   }
43 }

GraphQL variables

1 {
2   "input": {
3       "productId": "bc/store/product/111",
4 
5       // For the channel locale
6       "context": {
7         "channelId": "bc/store/channel/1",
8         "locale": "en"
9       },
10       "ids": ["bc/store/productImage/371", "bc/store/productImage/372"]
11     }
12 }

Remove image visibility

The following example makes a product image not visible in a channel locale. To set the image visibility for the global store, don’t include the context field in the input.

Request

Response

Example mutation: Remove product image visibility from a channel locale

1 mutation ($input: RemoveImagesFromProductInput!) {
2   product {
3     removeImagesFromProduct(input: $input) {
4       images {
5         edges {
6           node {
7             id
8             altText
9             isThumbnail
10             sortOrder
11             urlStandard
12             urlZoom
13             addedToProduct
14             overrides(context: { channelId: "bc/store/channel/1", locale: "fr" }) {
15               edges {
16                 node {
17                   ... on ProductImagesOverridesForChannelLocale {
18                     context {
19                       channelId
20                       locale
21                     }
22                     altText
23                     sortOrder
24                     addedToProduct
25                   }
26                 }
27               }
28             }
29           }
30         }
31       }
32     }
33   }
34 }

GraphQL variables

1 {
2   "input": {
3     "productId": "bc/store/product/111",
4     "context": {
5       "channelId": "bc/store/channel/1",
6       "locale": "fr"
7     },
8     "ids": ["bc/store/productImage/371", "bc/store/productImage/372"]
9   }
10 }

Product image information

Set image information

The following example sets product image information for the global store and a channel locale.

Request

Response

Example mutation: Set global product image information

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 mutation ($input: UpdateProductImagePropertiesInput!) {
7   product {
8     updateProductImageProperties(input: $input) {
9       images {
10         edges {
11           node {
12             id         
13             altText  
14             isThumbnail  
15             sortOrder  
16             urlStandard 
17             urlZoom
18             addedToProduct    
19             overrides( context: {channelId: "bc/store/channel/1", locale: "en"}) {
20               edges {
21                 node {
22                   ... on ProductImagesOverridesForChannelLocale {
23                     context {
24                       channelId
25                       locale
26                     }
27                     sortOrder
28                     altText
29                     isThumbnail
30                     addedToProduct
31                   }
32                 }
33               }
34             }
35           }
36         }
37       }
38     }
39   }
40 }

GraphQL variables

1 {
2   "input": {
3     "productId": "bc/store/product/111",
4     "data": [
5       {
6         "imageId": "bc/store/productImage/371",
7         "sortOrder": 2, 
8         "altText": "Global alt text", 
9         "isThumbnail": true, 
10         "overrides": [
11           {
12             "channelLocaleOverrides": {
13               "context": {
14                 "channelId": "bc/store/channel/1", 
15                 "locale": "en"
16               },
17               "data": {
18                 "sortOrder": 1, 
19                 "altText": "Channel-specific alt text",
20                 "isThumbnail": true 
21               }
22             }
23           }
24         ]
25       },
26       {
27         "imageId": "bc/store/productImage/372", 
28         "sortOrder": 1, 
29         "altText": "Global alt text",
30         "isThumbnail": false
31       }
32     ]
33   }
34 }

Remove image information from a locale

The following example removes product image overrides for the channel locale.

Request

Response

Example mutation: Remove product image overrides for a locale

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 mutation removeProductImagePropertiesOverrides($input: RemoveProductImagePropertiesOverridesInput!) {
7   product {
8     removeProductImagePropertiesOverrides(input: $input) {
9       images {
10         edges {
11           node {            
12             id        
13             altText    
14             isThumbnail  
15             sortOrder  
16             urlStandard 
17             urlZoom
18             addedToProduct
19             overrides ( context: { channelId: "bc/store/channel/1", locale: "en"}) {
20               edges {
21                 node {
22                   ... on ProductImagesOverridesForChannelLocale {
23                     context {
24                       channelId
25                       locale
26                     }
27                     altText
28                     isThumbnail
29                     sortOrder
30                     addedToProduct
31                   }
32                 }
33               }
34             }
35           } 
36         }
37       }
38     }
39   }
40 }

GraphQL variables

1 {
2   "input": {
3     "productId": "bc/store/product/111",
4     "data": [
5       {
6         "imageId": "bc/store/productImage/371",
7         "contexts": [
8           {
9             "channelLocaleContext": {
10               "channelId": "bc/store/channel/1", 
11               "locale": "en"
12             }
13           }
14         ]
15       }
16     ]
17   }
18 }

Query image information

The following example retrieves product image information. You can retrieve global information for the store and overrides for the channel locale.

You can also use the imagesOverrides node to retrieve overrides. This node will return only the images with overrides in the specific channel locale.

Request

Response

Example query: Get product image information

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 query {
7   store {
8     product(id: "bc/store/product/111") {
9       images {
10         edges {
11           node {
12             id        
13             altText    
14             isThumbnail  
15             sortOrder  
16             urlStandard 
17             urlZoom
18             addedToProduct
19             overrides( context: {channelId: "bc/store/channel/1", locale: "en"}) {
20               edges {
21                 node {
22                   ... on ProductImagesOverridesForChannelLocale {
23                     context {
24                       channelId
25                       locale
26                     }
27                     altText
28                     isThumbnail
29                     sortOrder
30                     addedToProduct
31                   }
32                 }
33               }
34             }
35           }
36         }
37       }
38     }
39   }
40 }

1	POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2	X-Auth-Token: {{ACCESS_TOKEN}}
3	Content-Type: application/json
4	Accept: application/json
5
6	mutation ($input: AddImagesToProductInput!) {
7	product {
8	addImagesToProduct(input: $input) {
9	images {
10	edges {
11	node {
12	id
13
14	# For the global store
15	altText
16	isThumbnail
17	sortOrder
18	urlStandard
19	urlZoom
20	addedToProduct
21
22	# For the channel locale
23	overrides (context: {channelId: "bc/store/channel/1", locale: "en"} ) {
24	edges {
25	node {
26	... on ProductImagesOverridesForChannelLocale {
27	context {
28	channelId
29	locale
30	}
31	altText
32	sortOrder
33	addedToProduct
34	}
35	}
36	}
37	}
38	}
39	}
40	}
41	}
42	}
43	}

1	{
2	"input": {
3	"productId": "bc/store/product/111",
4
5	// For the channel locale
6	"context": {
7	"channelId": "bc/store/channel/1",
8	"locale": "en"
9	},
10	"ids": ["bc/store/productImage/371", "bc/store/productImage/372"]
11	}
12	}

1	mutation ($input: RemoveImagesFromProductInput!) {
2	product {
3	removeImagesFromProduct(input: $input) {
4	images {
5	edges {
6	node {
7	id
8	altText
9	isThumbnail
10	sortOrder
11	urlStandard
12	urlZoom
13	addedToProduct
14	overrides(context: { channelId: "bc/store/channel/1", locale: "fr" }) {
15	edges {
16	node {
17	... on ProductImagesOverridesForChannelLocale {
18	context {
19	channelId
20	locale
21	}
22	altText
23	sortOrder
24	addedToProduct
25	}
26	}
27	}
28	}
29	}
30	}
31	}
32	}
33	}
34	}

1	{
2	"input": {
3	"productId": "bc/store/product/111",
4	"data": [
5	{
6	"imageId": "bc/store/productImage/371",
7	"sortOrder": 2,
8	"altText": "Global alt text",
9	"isThumbnail": true,
10	"overrides": [
11	{
12	"channelLocaleOverrides": {
13	"context": {
14	"channelId": "bc/store/channel/1",
15	"locale": "en"
16	},
17	"data": {
18	"sortOrder": 1,
19	"altText": "Channel-specific alt text",
20	"isThumbnail": true
21	}
22	}
23	}
24	]
25	},
26	{
27	"imageId": "bc/store/productImage/372",
28	"sortOrder": 1,
29	"altText": "Global alt text",
30	"isThumbnail": false
31	}
32	]
33	}
34	}