Lab - Variants, Variant Options, and Modifier Options

Plan: Developer Foundations

Lesson 8 of 21 · 45 min

This lab activity will give you a chance to practice working with variants, variant options, and modifiers via the Catalog API. Each step will walk you through how to use all of the endpoints covered in the previous lesson.

Prerequisites

BigCommerce store (sandbox or live)
Basic knowledge of APIs
REST client (Postman)
Completion of Catalog API labs 01 and 02

In this lab, you will:

Create a simple product
Create a variant option
GET variant options
Create a variant
GET all variants
Create a product and it’s variants in a single call
Add a modifier option with price adjuster to an existing product

Create a Simple Product

Open Postman
Copy and paste the request below into Postman

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products

Find a product with the same category id to which your new product will be added

Finding a category ID

The four required fields for a product are name, price, weight, and type.

Copy and paste the code below into the Body section of Postman

a. Under the URL field, click Body

{
  "name": "Shirt",
  "price": 10,
  "categories": [{id}],
  "weight": 4,
  "type": "physical"
}

Edit the request body

a. Replace {id} with the category id

Editing the request body

Select POST next to the request url
Click the Send button
Observe response and the product created in the store
Copy the product ID for next steps

If you are in MSF, creating the product isn’t enough to see it on the storefront, you also need a channel assignment.

There are a number of ways to gather a category’s ID. The video below walks you through identifying a category’s ID from the URL used to access the Edit a Category page in the control panel.

Alternatively, you can send a GET request to the categories endpoint to retrieve a category ID and then skip to Step 2:

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/categories?include_fields=name

Create Variant Options

Create a Variant Option for ‘Size’

Copy and paste the request below into Postman

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/:product_id/options

Enter the ID for the product created in Step 1 as the value of product_id in the Params tab
Copy and paste the code below into the Body section of Postman

{
   "display_name":"Size",
    "type":"rectangles",
    "option_values": [
                {
                    "is_default": true,
                    "label": "Large"
                },
                {
                    "label": "Medium"
                }
            ]
}

Select POST next to the request url
Click the Send button
Observe the changes in the response and Sizes added to product

Size option response

Sizes added to product

Create a Variant Option for ‘Color’

Copy and paste the request below into Postman

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/:product_id/options

Enter the ID for the product created in Step 1 as the value of product_id in the Params tab
Copy and paste the code below into the Body section of Postman

{
  "display_name": "Color",
  "type": "rectangles",
  "option_values": [
    {
      "is_default": true,
      "label": "Red"
    },
    {
      "label": "Blue"
    }
  ]
}

Select POST next to the request url
Click the Send button
Observe the changes in the response and Colors added to product

Color option response

Colors added to product

GET All Variant Options

Copy and paste the request below into Postman

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/:product_id/options

Enter the ID of the product used in the previous steps as the value of product_id in the Params tab
Select GET next to the request url (if not already selected)
Click the Send button
Observe response and copy the option IDs and variant option IDs (paste into text editor for use in next steps)

Option IDs and variant option IDs in response

Create a Variant

In this step you will create a variant for a Large Red Shirt.

Copy and paste the request below into Postman

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/:product_id/variants

Enter the ID of a product used in previous steps as the value for product_id in the Params tab
Copy and paste the code below into the Body section of Postman
Replace the {id} in the body request below with option IDs and variant option IDs copied in previous step

{
   "sku": "SKU-R-LG",
   "price": "10.00",
   "inventory_level": "5",
   "option_values": [
       {
            "id": {{id}},
            "option_id": {{id}}
      },
     {
            "id": {{id}},
            "option_id": {id}
      }
   ]
}

The option_values array combines the options Large and Red to create the SKU SKU-R-LG. The id in the option_values array is the id from the variant option response option_values > id (in other words, the id for the value of RED). The option_id is the id of the variant option itself (in other words, the id for the option COLOR).

Select POST next to the request url
Click the Send button
Observe the changes in the response and SKU/Variant added to product

SKU/Variant created on product

GET All Variants

Copy and paste the request below into Postman

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/:product_id/variants

Enter the ID of the product used in previous steps as the value for product_id in the Params tab
Select GET next to the request url (if not already selected)
Click the Send button
Observe response

Create a Product and All of Its Variants in a Single Call

Gather a category ID - use one of the methods from the first activity in this lab
Copy and paste the request below into Postman

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products

Copy and paste the code below into the Body section of Postman

{
    "name": "Awesome Shirt",
    "type": "physical",
    "price": 10.25,
    "description": "<h4>Great shirt</h4>The best shirt ever.",
    "weight": 1.20,
    "categories": [
        {id}
    ],
    "variants": [
        {
            "sku": "SKU-R-SM",
            "option_values": [
                {
                    "option_display_name": "Color",
                    "label": "Red"
                },
                {
                    "option_display_name": "Size",
                    "label": "Small"
                }
            ]
        },
        {
            "sku": "SKU-B-SM",
            "option_values": [
                {
                    "option_display_name": "Color",
                    "label": "Blue"
                },
                {
                    "option_display_name": "Size",
                    "label": "Small"
                }
            ]
        },
        {
            "sku": "SKU-R-MD",
            "option_values": [
                {
                    "option_display_name": "Color",
                    "label": "Red"
                },
                {
                    "option_display_name": "Size",
                    "label": "Medium"
                }
            ]
        },
        {
            "sku": "SKU-B-MD",
            "option_values": [
                {
                    "option_display_name": "Color",
                    "label": "Blue"
                },
                {
                    "option_display_name": "Size",
                    "label": "Medium"
                }
            ]
        },
        {
            "sku": "SKU-R-LRG",
            "price": 10.50,
            "weight": 1.25,
            "option_values": [
                {
                    "option_display_name": "Color",
                    "label": "Red"
                },
                {
                    "option_display_name": "Size",
                    "label": "Large"
                }
            ]
        },
        {
            "sku": "SKU-B-LG",
            "price": 10.50,
            "weight": 1.25,
            "option_values": [
                {
                    "option_display_name": "Color",
                    "label": "Blue"
                },
                {
                    "option_display_name": "Size",
                    "label": "Large"
                }
            ]
        }
    ]
}

In the request body, replace the category {id} with the ID copied in previous step
Select POST next to the request url
Click the Send button
Observe response and product created in store

Create Modifier Options

Add a Modifier Option with Price Adjuster to a Product

Copy and paste the request below into Postman

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/:product_id/modifiers

Enter the ID of the product used in previous steps as the value for product_id in the Params tab
Copy and paste the code below into the Body section of Postman

{
  "type": "checkbox",
  "required": false,
  "config": {
    "default_value": "Yes",
    "checked_by_default": false,
    "checkbox_label": "Check for Donation"
  },
  "display_name": "Add a $5 Donation"
}

Select POST next to the request url
Click the Send button
Observe response and modifier option added to product
Copy modifier ID for next step

Update the Modifier Option Value

Copy and paste the request below into Postman

https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/:product_id/modifiers/:modifier_id/values/:value_id

Enter the ID of the product used in previous steps as the value for product_id in the Params tab
Enter the ID of the modifier created in the previous step as the value for modifier_id in the Params tab
Enter the ID of the “Yes” value in modifier option as the value for product_id in the Params tab
Copy and paste the code below into the Body section of Postman

{
  "is_default": false,
  "adjusters": {
    "price": {
      "adjuster": "relative",
      "adjuster_value": 5
    }
  }
}

Select PUT next to the request url
Click the Send button
Observe response