Configurable products specifications

Some products have configurations associated with them. For example, customers can add a variety of things to sandwiches, such as lettuce, tomatoes, and onions. To define these configurations, use the configurable_products field.

info

To enable configurable products for your storefront, contact your Instacart representative.

Request

Field	Data type	Example
configurable_products	JSON	See Example.

Before you send your files, consider using a JSON validator.

JSON data

Field Definitions	Required	Type	Description	Example
config_id	Yes	string	A unique product configuration ID provided for this specific configuration.	"1234"
lead_time	No	integer	Lead time for this configuration in minutes.	1440 (24 hours)
config_type	Yes	string	Type of product configuration. Possible values: - prep_style: Use for scenarios such as a cut of a deli meat or cheese - custom: Use for scenarios such as a cake with custom text - builder: Use for scenarios such as a sandwich, pizza, or burger with configurable toppings	"builder"
status	Yes	boolean	Indicates whether to enable this configuration.	TRUE FALSE
options	Yes	array	An array with all the configuration options.
options[] .config_option_id	Yes	string	Unique product configuration option ID.	"12341"
options[] .name	Yes	string	Option name displayed to the customer.	"Bread"
options[] .type	Yes	string	The type of option. Possible values: - base_selection: Base item allowing additional options. - single_selection: single item must be selected - multiple_selection: multiple items can be selected - text: single line text field - text_field: multi line text field	"single_selection"
options[] .status	Yes	boolean	Indicates whether to enable this option.	TRUE FALSE
options[] .mandatory	Yes	boolean	Indicates whether this option is mandatory for a customer to select.	TRUE FALSE
options[] .default_text	No	string	Default text when options[].type is text or text_field	"Happy Birthday!"
options[] .price	No	string	Price of the option.	"5.00"
options[] .items	No	array	Array of product configuration option items.
options[] .max_length	No	integer	Maximum length of text or text_field types.	30
options[] .maximum_selection	No	integer	When options[].type is multiple_selection, the maximum number of items that can be selected for this option.	8
options[] .incompatible_configuration_options	No	array	Array consisting of child arrays of incompatible option item IDs.	[ ["config_option_123", "config_option_456"] ["config_option_456"] ]
options[] .incompatible_configuration_options[]	No	array	Array of incompatible option item IDs. Used to hide this option when another option is enabled.	["config_option_321"]
options[] .required_configuration_options	No	array	Array consisting of child arrays of required option item IDs.	[ ["config_option_123", "config_option_456"] ["config_option_321"] ]
options[] .required_configuration_options[]	No	array	Array of required option item IDs. Used to hide this option unless another option is enabled.	["config_option_321"]
options[] .items[] .config_option_item_id	Yes	string	Unique option item ID. This is unique within the entire object.	"123411"
options[] .items[] .name	No	string	The name of the option item displayed to the customer.	"Whole wheat"
options[] .items[] .default	No	boolean	Indicates whether the item is selected by default.	TRUE FALSE
options[] .items[] .price	No	string	Price of the option.	"1.00"
options[] .items[] .status	Yes	boolean	Indicates whether to enable this item in the option.	TRUE FALSE
options[] .items[] .lead_time_change	No	integer	How much extra time (minutes) this option adds to the lead_time.	15 (minutes)
options[] .items[] .storage_temp_override	No	string	Override the base storage temperature setting with additional heating or freezing.	"heated"
options[] .items[] .incompatible_configuration_options	No	array	Array consisting of child arrays of incompatible option item IDs.	[ ["config_option_123", "config_option_456"] ["config_option_321"] ]
options[] .items[] .incompatible_configuration_options[]	No	array	Array of incompatible option item IDs. Used to hide this option when another option is enabled.	["config_option_321"]
options[] .items[] .required_configuration_options	No	array	Array consisting of child arrays of required option item IDs.	[ ["config_option_123", "config_option_456"] ["config_option_456"] ]
options[] .items[] .nutri_info	No	object	Nutrition information
options[] .items[] .nutri_info.calories_per_serving	No	integer	Calories added by this option.	180
options[] .items[] .selection_options[]	No	array	Array of additional options. For example, after a customer selects a pizza sauce, they can select "Light", "Normal", or "Extra" sauce.
options[] .items[] .selection_options[] .selection_option_id	Yes	string	Unique selection_option_id for each parent selection_option.	“152”
options[] .items[] .selection_options[] .default_option_id	No	string	Default for the additional option.	“152-2”
options[] .items[] .selection_options[] .name	Yes	string	Name displayed to customer.	“What side?”
options[] .items[] .selection_options[] .options[].id	Yes	string	Unique option ID.	“152-2”
options[] .items[] .selection_options[] .options[].name	Yes	string	Name displayed to customer.	“Sweet potato fries”

Example

{
  "config_id": "sandwich-120",
  "lead_time": 1440,
  "config_type": "builder",
  "options": [
    {
      "config_option_id": "10",
      "name": "Bread",
      "type": "single_selection",
      "mandatory": true,
      "price": null,
      "items": [
        {
          "config_option_item_id": "10-1",
          "name": "Whole Wheat",
          "nutri_info": {
            "calories_per_serving": 120
          },
          "default": true,
          "price": null
        },
        {
          "config_option_item_id": "10-2",
          "name": "White",
          "nutri_info": {
            "calories_per_serving": 80
          },
          "default": false,
          "price": null
        }
      ]
    },
    {
      "config_option_id": "11",
      "name": "Premium Addons",
      "type": "multiple_selection",
      "mandatory": true,
      "price": null,
      "items": [
        {
          "config_option_item_id": "11-1",
          "name": "Avocado",
          "nutri_info": {
            /* Avocado adds 60 calories to the total calorie count */
            "calories_per_serving": 60
          },
          /* Avocado adds 60 cents to the base price of the item */
          "price": 0.6
        },
        {
          "config_option_item_id": "11-2",
          "name": "Bacon",
          "nutri_info": {
            /* Bacon adds 200 calories to the total calorie count */
            "calories_per_serving": 200
          },
          /* Bacon adds $1.50 to the base price of the item */
          "price": 1.5
        }
      ]
    }
  ]
}