Product Modifier Options

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.

Using the Catalog features of the Admin API, you can set and query information about a product modifier options, for example, option name and values.

You can perform the following:

You can also set and remove information for shared modifiers. The changes affect all products that you assign to the shared modifier. Querying modifier options returns all modifiers, including shared ones.

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.

Set product modifier options

Set information about a product modifier option for a store or a locale within a storefront channel.

The following mutations let you set the name and values for existing modifier options. You must first create the modifier option for the product through the control panel or the REST Create a product modifier endpoint.

The responses may include all modifier options, including those that are shared. However, to set shared modifier options, use the mutations in Set shared modifier options.

Set product modifier options at the global level

The following example sets global product modifier information for the store, from which channels inherit by default. You can set the modifier name and values.

Example mutation: Set product modifier options at the global level
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6mutation ($input: SetProductModifiersInformationInput!) {
7 product {
8 setProductModifiersInformation (input: $input) {
9 product {
10 id
11 modifiers {
12 edges {
13 node {
14 id
15 displayName
16 isRequired
17 isShared
18 ... on CheckboxProductModifier {
19 checkedByDefault
20 fieldValue
21 }
22 ... on TextFieldProductModifier {
23 defaultValue
24 }
25 ... on MultilineTextFieldProductModifier {
26 defaultValue
27 }
28 ... on NumbersOnlyTextFieldProductModifier {
29 defaultValueFloat: defaultValue
30 }
31 ... on DropdownProductModifier {
32 values {
33 id
34 label
35 isDefault
36 }
37 }
38 ... on RadioButtonsProductModifier {
39 values {
40 id
41 label
42 isDefault
43 }
44 }
45 ... on RectangleListProductModifier {
46 values {
47 id
48 label
49 isDefault
50 }
51 }
52 ... on SwatchProductModifier {
53 values {
54 id
55 label
56 isDefault
57 }
58 }
59 }
60 }
61 }
62 }
63 }
64 }
65}
GraphQL variables
1{
2 "input": {
3 "productId": "bc/store/product/111",
4 "data": {
5 "modifiers": [
6 {
7 "modifierId": "bc/store/productModifier/121",
8 "data": {
9 "rectangleList": {
10 "displayName": "Holiday Theme",
11 "values": [
12 {
13 "valueId": "bc/store/productModifierValue/113",
14 "label": "Birthday"
15 },
16 {
17 "valueId": "bc/store/productModifierValue/114",
18 "label": "Christmas"
19 }
20 ]
21 }
22 }
23 }
24 ]
25 }
26 }
27}

Set product modifier options for a locale

The following example sets product modifier option information for the locale within the specified storefront channel. These will override global store information. You can set the modifier option name and values.

Example mutation: Set product modifier options for a locale
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6mutation ($input: SetProductModifiersInformationInput!) {
7 product {
8 setProductModifiersInformation (input: $input) {
9 product {
10 id
11 modifiers {
12 edges {
13 node {
14 id
15 displayName
16 ... on CheckboxProductModifier {
17 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr"}) {
18 displayName
19 fieldValue
20 }
21 }
22 ... on TextFieldProductModifier {
23 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr"}) {
24 displayName
25 defaultValue
26 }
27 }
28 ... on MultilineTextFieldProductModifier {
29 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr"}) {
30 displayName
31 defaultValue
32 }
33 }
34 ... on NumbersOnlyTextFieldProductModifier {
35 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr"}) {
36 displayName
37 defaultValueFloat: defaultValue
38 }
39 }
40 ... on DropdownProductModifier {
41 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr"}) {
42 displayName
43 values {
44 id
45 label
46 }
47 }
48 }
49 ... on RadioButtonsProductModifier {
50 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr"}) {
51 displayName
52 values {
53 id
54 label
55 }
56 }
57 }
58 ... on RectangleListProductModifier {
59 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr"}) {
60 displayName
61 values {
62 id
63 label
64 }
65 }
66 }
67 ... on SwatchProductModifier {
68 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr"}) {
69 displayName
70 values {
71 id
72 label
73 }
74 }
75 }
76 ... on FileUploadProductModifier {
77 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr"}) {
78 displayName
79 }
80 }
81 ... on DateFieldProductModifier {
82 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr"}) {
83 displayName
84 }
85 }
86 }
87 }
88 }
89 }
90 }
91 }
92}
GraphQL variables
1{
2 "input": {
3 "productId": "bc/store/product/111",
4 "localeContext": {
5 "channelId": "bc/store/channel/2",
6 "locale": "fr"
7 },
8 "data": {
9 "modifiers": [
10 {
11 "modifierId": "bc/store/productModifier/121",
12 "data": {
13 "rectangleList": {
14 "displayName": "Thème de vacances",
15 "values": [
16 {
17 "valueId": "bc/store/productModifierValue/113",
18 "label": "Anniversaire"
19 },
20 {
21 "valueId": "bc/store/productModifierValue/114",
22 "label": "Noël"
23 }
24 ]
25 }
26 }
27 }
28 ]
29 }
30 }
31}

Remove product modifier options for a locale

The following example removes product modifier option information for the locale within the specified storefront channel.

Example mutation: Remove product modifier options for a locale
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6mutation ($input: RemoveProductModifiersOverridesInput!) {
7 product {
8 removeProductModifiersOverrides (input: $input) {
9 product {
10 id
11 modifiers {
12 edges {
13 node {
14 id
15 displayName
16 }
17 }
18 }
19 }
20 }
21 }
22}
GraphQL variables
1{
2 "input": {
3 "productId": "bc/store/product/111",
4 "localeContext": {
5 "locale": "fr",
6 "channelId": "bc/store/channel/2"
7 },
8 "data": {
9 "modifiers": [
10 {
11 "modifierId": "bc/store/productModifier/118",
12 "data": {
13 "checkbox": {
14 "fields": [
15 "CHECKBOX_PRODUCT_MODIFIER_DISPLAY_NAME_FIELD"
16 ]
17 }
18 }
19 }
20 ]
21 }
22 }
23}

Set shared modifier options

You can set information about a shared modifier option for a store or a locale within a storefront channel. You must first create the shared modifier options through the control panel. Changing a shared modifier option affects all products that you assign to the shared modifier option. You cannot customize shared modifier options on a product level.

The following mutations let you set the name and values for existing shared modifiers.

Set shared modifier options at the global level

The following example sets global shared modifier information for the store, from which channels inherit by default. You can set the name and values for existing modifiers.

Example mutation: Set shared modifier options at the global level
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6mutation ($input: SetSharedProductModifiersInformationInput!) {
7 sharedProductModifiers {
8 setSharedProductModifiersInformation (input: $input) {
9 sharedProductModifiers {
10 id
11 }
12 }
13 }
14}
GraphQL variables
1{
2 "input": {
3 "data": {
4 "modifiers": [
5 {
6 "modifierId": "bc/store/sharedProductModifier/2",
7 "data": {
8 "rectangleList": {
9 "displayName": "Button type",
10 "values": [
11 {
12 "valueId": "bc/store/sharedProductModifierValue/107",
13 "label": "Large buttons"
14 },
15 {
16 "valueId": "bc/store/sharedProductModifierValue/108",
17 "label": "Small buttons"
18 }
19 ]
20 }
21 }
22 }
23 ]
24 }
25 }
26}

Set shared modifier options for a locale

The following example sets shared modifier information for the locale within the specified storefront channel. These override global store information. You can set the name and values for existing modifiers.

Example mutation: Set shared modifier options for a locale
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6mutation ($input: SetSharedProductModifiersInformationInput!) {
7 sharedProductModifiers {
8 setSharedProductModifiersInformation (input: $input) {
9 sharedProductModifiers {
10 id
11 }
12 }
13 }
14}
GraphQL variables
1{
2 "input": {
3 "localeContext": {
4 "channelId": "bc/store/channel/2",
5 "locale": "fr"
6 },
7 "data": {
8 "modifiers": [
9 {
10 "modifierId": "bc/store/sharedProductModifier/2",
11 "data": {
12 "rectangleList": {
13 "displayName": "bouton",
14 "values": [
15 {
16 "valueId": "bc/store/sharedProductModifierValue/107",
17 "label": "grande"
18 },
19 {
20 "valueId": "bc/store/sharedProductModifierValue/108",
21 "label": "petite"
22 }
23 ]
24 }
25 }
26 }
27 ]
28 }
29 }
30}

Remove shared modifier options for a locale

The following example removes shared modifier option information for the locale within the specified storefront channel.

Example mutation: Remove shared modifier options for a locale
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6mutation ($input: RemoveSharedProductModifiersOverridesInput!) {
7 sharedProductModifiers {
8 removeSharedProductModifiersOverrides (input: $input) {
9 sharedProductModifiers {
10 id
11 }
12 }
13 }
14}
GraphQL variables
1{
2 "input": {
3 "localeContext": {
4 "channelId": "bc/store/channel/2",
5 "locale": "fr"
6 },
7 "data": {
8 "modifiers": [
9 {
10 "modifierId": "bc/store/sharedProductModifier/1",
11 "data": {
12 "textField": {
13 "fields": ["SHARED_TEXT_FIELD_PRODUCT_MODIFIER_DEFAULT_VALUE_FIELD"]
14 }
15 }
16 }
17 ]
18 }
19 }
20}

Query modifier options

The following example retrieves modifier information. You can retrieve global information for the store and overrides for the locale within the specified storefront channel. The query returns all modifier options, including those that are shared.

Example query: Get modifier options
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6query {
7 store {
8 product (id: "bc/store/product/111") {
9 id
10 modifiers (first: 10) {
11 edges {
12 node {
13 __typename
14 id
15 displayName
16 isShared
17 isRequired
18 ... on CheckboxProductModifier {
19 checkedByDefault
20 fieldValue
21 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
22 displayName
23 fieldValue
24 }
25 }
26 ... on TextFieldProductModifier {
27 defaultValue
28 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
29 displayName
30 defaultValue
31 }
32 }
33 ... on MultilineTextFieldProductModifier {
34 defaultValue
35 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
36 displayName
37 defaultValue
38 }
39 }
40 ... on NumbersOnlyTextFieldProductModifier {
41 defaultValueFloat: defaultValue
42 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
43 displayName
44 defaultValueFloat: defaultValue
45 }
46 }
47 ... on DropdownProductModifier {
48 values {
49 id
50 label
51 isDefault
52 }
53 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
54 displayName
55 values {
56 id
57 label
58 }
59 }
60 }
61 ... on RadioButtonsProductModifier {
62 values {
63 id
64 label
65 isDefault
66 }
67 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
68 displayName
69 values {
70 id
71 label
72 }
73 }
74 }
75 ... on RectangleListProductModifier {
76 values {
77 id
78 label
79 isDefault
80 }
81 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
82 displayName
83 values {
84 id
85 label
86 }
87 }
88 }
89 ... on SwatchProductModifier {
90 values {
91 id
92 label
93 isDefault
94 }
95 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
96 displayName
97 values {
98 id
99 label
100 }
101 }
102 }
103 ... on FileUploadProductModifier {
104 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
105 displayName
106 }
107 }
108 ... on DateFieldProductModifier {
109 overridesForLocale (localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
110 displayName
111 }
112 }
113 }
114 }
115 }
116 }
117 }
118}

You can retrieve overrides for multiple locales in a channel, as shown in the following example:

Example query: Get modifier options
1POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2X-Auth-Token: {{ACCESS_TOKEN}}
3Content-Type: application/json
4Accept: application/json
5
6query {
7 store {
8 product (id: "bc/store/product/111") {
9 id
10 modifiers (first: 1) {
11 edges {
12 node {
13 __typename
14 id
15 displayName
16 isShared
17 isRequired
18
19 // modifier values for rectangle List product modifiers
20 ... on RectangleListProductModifier {
21
22 // global values for the store
23 values {
24 id
25 label
26 isDefault
27 }
28
29 // overrides for the UK locale in channel 2
30 uk: overridesForLocale(localeContext: { channelId: "bc/store/channel/2", locale: "uk" }) {
31 displayName
32 values {
33 id
34 label
35 }
36 }
37
38 // overrides for the France locale in channel 2
39 fr: overridesForLocale(localeContext: { channelId: "bc/store/channel/2", locale: "fr" }) {
40 displayName
41 values {
42 id
43 label
44 }
45 }
46 }
47 }
48 }
49 }
50 }
51 }
52}