ArchiveStore OperationsCatalog V2 Products

Option Values

Deprecated

Option Values

Values that can be selected for an option.

This is archived documentation. The V2 Catalog API is deprecated. For current API documentation, see the Catalog API.

NameTypeDescription
idintA unique, read-only value that identifies this option value.
option_idintA read-only value identifying the option to which this option value is assigned.
labelstringThe name of the label. Cannot be the same as the label of another value already assigned to the option.
sort_orderint
valuetextAcceptable values generally depend on the option type, as defined in the option:

RB: string to be displayed to the customer.
RT: string to be displayed to the customer.
S: string to be displayed to the customer.
P: product ID;
PI: product ID.
CS: one of the following color values – a hexadecimal color code to create a color option (e.g., #0f0000);
a CSS 2.1 color name (e.g., blue);
up to three hexadecimal color codes and/or color names, separated by pipe symbols (e.g., #FF0000|lime|#0000FF);
a URI to an image to create a texture (e.g., http://store.com/images/myimg.png);
or the name of an image file in the store’s WebDAV import folder (e.g., myimg.png).
is_defaultbooleanWhether or not this value is selected by default. For each option, only one option value can be selected by default.

Gets the values belonging to an option. (Default sorting is by option-value id, from lowest to highest.)

GET /stores/{store_hash}/v2/options/{option_id}/values

Pagination

Parameters can be added to the URL query string to paginate the collection. The maximum limit is 250. If a limit isn’t provided, up to 50 option_values are returned by default.

ParameterTypeExample
Pageint/api/v2/options/{option_id}/values?page={number}
Limitint/api/v2/options/{option_id}/values?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "option_id": 3,
    "label": "Silver",
    "sort_order": 2,
    "value": "#cccccc",
    "is_default": true
  },
  {
    "id": 2,
    "option_id": 3,
    "label": "Black",
    "sort_order": 1,
    "value": "#000000",
    "is_default": false
  }
]

Gets an option value.

GET /stores/{store_hash}/v2/options/{option_id}/values/{id}

Response

Example JSON returned in the response:

{
  "id": 9,
  "option_id": 3,
  "label": "Purple",
  "sort_order": 3,
  "value": "#700170",
  "is_default": false
}

Creates a new option value.

POST /stores/{store_hash}/v2/options/{option_id}/values

Read-only Properties

The following properties of the option value are read-only. If one or more of these properties are included in the request, it will be rejected.

  • id
  • option_id

Requirements

The following properties of the option value are required. The request won’t be fulfilled unless these properties are valid.

  • label
  • value

Note

To maximize system performance, BigCommerce caps the total number of values per option at 250. IF the option has 250 values and you try to create another one, BigCommerce will return a 403 error.

When you POST an is_defaultproperty of true, all other option values on the parent option will have their is_default property set to false.

Request

Example request object:

{
  "label": "white",
  "sort_order": 0,
  "value": "#FFFFFF",
  "is_default": true
}

Response

Example JSON returned in the response:

{
  "id": 68,
  "option_id": 3,
  "label": "white",
  "sort_order": 0,
  "value": "#FFFFFF",
  "is_default": true
}

Updates an existing option value.

PUT /stores/{store_hash}/v2/options/{option_id}/values/{id}

Read-only Properties

The following properties of the option value are read-only. If one or more of these properties are included in the request, it will be rejected.

  • id
  • option_id

Requirements

The following properties of the option value are required. The request won’t be fulfilled unless these properties are valid.

Notes

When you PUT an is_default property of true, all other option values on the parent option will have their is_default property set to false.

Request

Example request object:

{
  "label": "whitish",
  "sort_order": 1,
  "value": "#FFFFEF",
  "is_default": true
}

Response

Example JSON returned in the response:

{
  "id": 68,
  "option_id": 3,
  "label": "whitish",
  "sort_order": 1,
  "value": "#FFFFEF",
  "is_default": true
}

Deletes an option value.

DELETE /stores/{store_hash}/v2/options/{option_id}/values/{id}

Deletes multiple values belonging to an option.

DELETE /stores/{store_hash}/v2/options/{option_id}/values

Pagination

Parameters can be added to the URL query string to paginate the collection. The maximum limit is 250. If a limit isn’t provided, up to 50 option_values are returned by default.

ParameterTypeExample
Pageint/api/v2/options/{option_id}/values?page={number}
Limitint/api/v2/options/{option_id}/values?limit={count}