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.

Parameters

The configurable_products object accepts the following parameters.

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 or visual options such as color swatches and style images. - builder: Use for scenarios such as a sandwich, pizza, or burger with configurable toppings. - pack: Use for meal packs or bundles where each option is a catalog product, such as a catering dinner pack.	"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. - multiselect_with_quantity: Multiple items can be selected, each with a quantity counter. - included: Fixed items always included in the pack. Items are displayed but cannot be deselected. Note: The Shopper App doesn't support the text and text_field options, which means that the text is not visible to shoppers.	"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. Note: The Shopper App doesn't support the text and text_field options, which means that the text is not visible to shoppers.	"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[] .minimum_selection	No	integer	When options[].type is multiselect_with_quantity, the minimum number of items that must be selected. Also defines the number of included items for surcharge calculation.	1
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[] .linked_lookup_code	No	string	Lookup code for the catalog product linked to this pack option. Required when config_type is pack.	"00819269011838"
options[] .items[] .image_url	No	string	URL for an image representing the option. When provided, the option displays as an image tile. Applies to the custom config type only. If the URL is unreachable, the option displays as text only.	"https://example.com/roses.png"
options[] .items[] .hex_color	No	string	Hex color code for the option. When provided, the option displays as a color swatch. Applies to the custom config type only. If both image_url and hex_color are provided, image_url takes precedence.	"#FFB6C1"
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"

Examples

The following example shows a builder configuration for a sandwich.

{
  "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
        }
      ]
    }
  ]
}

The following example shows a custom configuration for a birthday cake, with trim style options that use image_url and balloon color options that use hex_color and image_url.

{
  "config_id": "birthday-cake-001",
  "config_type": "custom",
  "status": true,
  "options": [
    {
      "config_option_id": "trim",
      "name": "Trim Style",
      "type": "single_selection",
      "status": true,
      "mandatory": true,
      "items": [
        {
          "config_option_item_id": "trim-1",
          "name": "Roses",
          "image_url": "https://example.com/cakes/roses.png",
          "default": true,
          "status": true
        },
        {
          "config_option_item_id": "trim-2",
          "name": "Stars",
          "image_url": "https://example.com/cakes/stars.png",
          "default": false,
          "status": true
        },
        {
          "config_option_item_id": "trim-3",
          "name": "Balloons",
          "image_url": "https://example.com/cakes/balloons.png",
          "default": false,
          "status": true
        }
      ]
    },
    {
      "config_option_id": "color",
      "name": "Balloon Color",
      "type": "single_selection",
      "status": true,
      "mandatory": true,
      "items": [
        {
          "config_option_item_id": "color-1",
          "name": "Multicolored - As Shown",
          "default": true,
          "status": true
        },
        {
          "config_option_item_id": "color-2",
          "name": "Pink",
          "hex_color": "#FFB6C1",
          "default": false,
          "status": true
        },
        {
          "config_option_item_id": "color-3",
          "name": "Yellow",
          "hex_color": "#FFEB3B",
          "default": false,
          "status": true
        },
        {
          "config_option_item_id": "color-4",
          "name": "Rainbow",
          "image_url": "https://example.com/cakes/rainbow-icing.png",
          "default": false,
          "status": true
        }
      ]
    },
    {
      "config_option_id": "message",
      "name": "Cake Message",
      "type": "text",
      "status": true,
      "mandatory": false,
      "default_text": "Happy Birthday!",
      "max_length": 50
    }
  ]
}