# Products

# Introduction

Commerce handles your inventory by maintaining an internal representation of the products that you have for sale.

This representation can be updated in real-time and allows Commerce to very quickly provide product details to user interfaces and to accurately validate transactions.

The simplest way to provide Commerce with the product details it needs is by creating a JSON manifest and then using the Import feature in the Admin.

# Definition

Commerce uses a JSON structure to define the products that are available for sale.

It provides the details that we require to display and transact the products on your behalf.

See the examples of common product use-cases.

To see the product definitions in action, check the Developer Notes links underneath each of the products within the Commerce Demo.

# Inventory JSON

When generating an inventory file for import into the Admin you should use the following format, where each of the entries is a product consisting of the Attributes shown below.

You can check the Examples below or this demo inventory.json to see a wide range of possible product definitions.

{
  "entries": [
    {
      "id": "product1",
      ...
    },
    {
      "id": "product2",
      ...
    },
    {
      "id": "product3",
      ...
    },
    {
      "id": "product4",
      ...
    },
    ...
  ]
}

# Attributes

# description

This attribute is optional.
It sets a short description for the product.
The value is displayed by the default User Interface.

"description": "T-Shirt Large Purple"

# digital

This attribute is optional.
It indicates if the product is a non-physical digital product.
When the value is true the product is ignored during shipping calculations.
When not supplied it is considered to be false.

"digital": true

# dimensions

This attribute is required for physical products.
It defines the dimensions of a physical product for use in shipping calculations.
The height, length & width must be in centimeters.
The weight must be in grams.

"dimensions": {
  "height": 30,
  "length": 30,
  "weight": 180,
  "width": 30
}

# fields

This attribute is optional.
It specifies input fields to be shown against the product.
The fields appear in the cart & checkout of the default User Interface.
Fields are sorted as per the fields array order.
In the case of a product group, the fields of the group will appear before sub-product fields.

"fields": [
  { "id": "cut", ...  },
  { "id": "smoked", ...  },
  { "id": "wrapped", ...  }
]

# Field Types

  • Select
    Displays a select box.
    If no type is specified it is considered to be select.

    {
      "id": "bomb1",
      "label": "Flavour #1",
      "options": [
        { "id": "Apple" },
        { "id": "Chamomile" },
        { "id": "Cherry" },
        { "id": "Eucalyptus" },
        { "id": "Green Tea" }
      ],
      "type": "select"
    }
    
  • Radio

    {
      "id": "bomb1",
      "label": "Flavour #1",
      "options": [
        { "id": "Apple" },
        { "id": "Chamomile" },
        { "id": "Cherry" },
        { "id": "Eucalyptus" },
        { "id": "Green Tea" }
      ],
      "type": "radio"
    }
    
  • Checkbox

    {
      "id": "bomb1",
      "label": "Flavours",
      "options": [
        { "id": "Apple" },
        { "id": "Chamomile" },
        { "id": "Cherry" },
        { "id": "Eucalyptus" },
        { "id": "Green Tea" }
      ],
      "type": "checkbox"
    }
    
  • Text

    {
      "id": "name",
      "label": "Recipient Name",
      "required": true,
      "type": "text"
    }
    
  • Textarea

    {
      "id": "message",
      "label": "Gift Message",
      "required": true,
      "type": "textarea"
    }
    
  • Number

    {
      "id": "length",
      "label": "Length (in meters)",
      "description": "Meters between 0.25 and 7.25",
      "maximum": 7.25,
      "minimum": 0.25,
      "precision": 2,
      "step": 0.25,
      "type": "number",
      "multiplier": true
    }
    

# Field Notes

  • Default Field Type
    If no 'type' is specified it will be a 'select'.

    {
      "id": "bomb1",
      "label": "Flavours",
      "options": [
        { "id": "Apple" },
        { "id": "Chamomile" },
        { "id": "Cherry" },
        { "id": "Eucalyptus" },
        { "id": "Green Tea" }
      ]
    }
    
  • Option Labels
    A 'label' can also be provided with options.

    {
      "id": "bomb1",
      "label": "Flavours",
      "options": [
        {
          "id": "apple",
          "label": "Apple"
        },
        {
          "id": "chamomile",
          "label": "Chamomile"
        },
        {
          "id": "cherry",
          "label": "Cherry"
        },
        {
          "id": "eucalyptus",
          "label": "Eucalyptus"
        },
        {
          "id": "greentea",
          "label": "Green Tea"
        }
      ]
    }
    
  • Option Delta Pricing
    A 'price' node can be set against any option to make it delta-priced.
    When the user selects the item it will adjust the product price accordingly.

    {
      "id": "bomb1",
      "label": "Flavours",
      "options": [
        {
          "id": "apple",
          "label": "Apple",
          "price": 1
        },
        {
          "id": "chamomile",
          "label": "Chamomile",
          "price": 2
        },
        {
          "id": "cherry",
          "label": "Cherry",
          "price": -0.5
        },
        {
          "id": "eucalyptus",
          "label": "Eucalyptus",
          "price": -1
        },
        {
          "id": "greentea",
          "label": "Green Tea",
          "price": 1.5
        }
      ]
    }
    

# id

This attribute is required.
The value must be unique.
It is used by the API (see: Commerce.cart.add)

"id": "galaxyearings1"

# image

This attribute is optional.
When an image is not supplied the image area in the default User Interface will be empty.
It sets the location of an image to represent the product.

"image": "https://demo.static.tools/media/images/simple-001.jpg"

# name

This attribute is required.
It sets the name of the product.
The value is displayed throughout the default User Interface.

"name": "C&G Vibrant Shirt"

# price

This attribute is required.
The price structure has several formats to support different pricing requirements.

  • Single Price List (Default), Single Currency (Default)
    Assumes that the price list is 'default' and that the currency is the default for the instance.

    "price": 2
    
  • Multiple Price Lists, Single Currency (Default)
    Defines several price lists and assumes that the currency for each is the default for the instance.

    "price": {
      "default": 12,
      "vip": 10,
      "wholesale": 8
    }
    
  • Single Price List, Multiple Currencies
    Defines the price list as 'default' and provides multiple currencies.

    "price": {
      "default": {
        "AUD": 17,
        "EUR": 11,
        "USD": 12
      }
    }
    
  • Multiple Price Lists, Multiple Currencies
    Defines several price lists and provides multiple currencies.

    "price": {
      "default": {
        "AUD": 17,
        "EUR": 11,
        "USD": 12
      },
      "vip": {
        "AUD": 15,
        "EUR": 9,
        "USD": 10
      },
      "wholesale": {
        "AUD": 12,
        "EUR": 7,
        "USD": 8
      }
    }
    
  • Single Price List, Single Currency, Bulk Pricing
    Defines the price list as 'default', the currency and bulk pricing thresholds.

    "price": {
      "default": {
        "AUD": {
          "1": 17,
          "5": 14,
          "10": 11
        }
      }
    }
    
  • Multiple Price Lists, Multiple Currencies, Bulk Pricing
    Defines several price lists, in multiple currencies with bulk pricing.

    "price": {
      "default": {
        "AUD": {
          "1": 17,
          "5": 14,
          "10": 11
        },
        "EUR": {
          "1": 11,
          "5": 9,
          "10": 7
        },
        "USD": {
          "1": 12,
          "5": 10,
          "10": 8
        }
      },
      "vip": {
        "AUD": {
          "1": 15,
          "5": 12,
          "10": 9
        },
        "EUR": {
          "1": 9,
          "5": 7,
          "10": 5
        },
        "USD": {
          "1": 10,
          "5": 8,
          "10": 6
        }
      },
      "wholesale": {
        "AUD": {
          "1": 12,
          "5": 9,
          "10": 6
        },
        "EUR": {
          "1": 7,
          "5": 5,
          "10": 3
        },
        "USD": {
          "1": 8,
          "5": 6,
          "10": 4
        }
      }
    }
    

# quantity

This attribute is optional.
It specifies restrictions on the product quantity.

"quantity": {
  "minimum": 5,
  "maximum": 30,
  "step": 5
}

The value of fixed will lock the quantity to the defined value.

"quantity": {
  "fixed": 1
}

# sku

This attribute is optional.
The value is displayed as the SKU on Invoices and within the Admin.

"sku": "ge003008"

# Examples

# Digital Only

{
  "digital": true,
  "id": "digital1",
  "image": "https://demo.static.tools/media/images/digital-001.jpg",
  "name": "Art Activities",
  "price": 2
}

# Physical

{
  "dimensions": {
    "height": 2,
    "length": 3,
    "weight": 18,
    "width": 2
  },
  "id": "simple1",
  "image": "https://demo.static.tools/media/images/simple-001.jpg",
  "name": "Galaxy Earings",
  "price": 17
}

# Configurable

To make a product configurable add a "fields" key with the fields to be set against the product.

See the full fields details for more information.

{
  "dimensions": {
    "height": 30,
    "length": 30,
    "weight": 180,
    "width": 30
  },
  "fields": [
    {
      "id": "bomb1",
      "label": "Flavour #1",
      "options": [
        { "id": "Apple" },
        { "id": "Chamomile" },
        { "id": "Cherry" },
        { "id": "Eucalyptus" },
        { "id": "Green Tea" }
      ]
    },
    {
      "id": "bomb2",
      "label": "Flavour #2",
      "options": [
        { "id": "Lavender" },
        { "id": "Lemon" },
        { "id": "Mango" },
        { "id": "Milk" },
        { "id": "Orange" }
      ]
    },
    {
      "id": "bomb3",
      "label": "Flavour #3",
      "options": [
        { "id": "Peppermint" },
        { "id": "Pineapple" },
        { "id": "Rose" },
        { "id": "Vanilla" },
        { "id": "Watermelon" }
      ]
    }
  ],
  "id": "configurable1",
  "image": "https://demo.static.tools/media/images/configurable-001.jpg",
  "name": "3 x Bath Bombs",
  "price": 24
}

# Delta Priced

To add Delta Pricing to a product, add a price attribute to the options that adjust the price.

{
  "dimensions": {
    "height": 4,
    "length": 30.48,
    "weight": 130,
    "width": 22.86
  },
  "fields": [
    {
      "id": "flavour",
      "label": "Flavour",
      "options": [
        {
          "id": "Natural"
        },
        {
          "id": "Smoked",
          "price": 1
        }
      ]
    },
    {
      "id": "size",
      "label": "Cut Size",
      "options": [
        {
          "id": "Regular"
        },
        {
          "id": "Thick Cut",
          "price": 3
        }
      ],
      "type": "radio"
    }
  ],
  "id": "delta1",
  "image": "https://demo.static.tools/media/images/delta-001.jpg",
  "name": "Salmon Fillets",
  "price": 12.5
}

# Fractional

To have Fractional Pricing specify a number field that acts as a multiplier on the other units.

{
  "dimensions": {
    "height": 4,
    "length": 30.48,
    "weight": 130,
    "width": 22.86
  },
  "fields": [
    {
      "id": "length",
      "label": "Length (in meters)",
      "description": "Meters between 0.25 and 7.25",
      "maximum": 7.25,
      "minimum": 0.25,
      "precision": 2,
      "step": 0.25,
      "type": "number",
      "multiplier": true
    }
  ],
  "id": "cgfabricpurple",
  "image": "https://demo.static.tools/media/images/fractional-001.jpg",
  "name": "C&G Fabric Purple",
  "price": 5,
  "quantity": {
    "fixed": 1
  }
}

# Composite

A Composite Product / Product Variations is used to allow the user to select from within a set of products that are differentiated by tehir attributes.

When a product contains a products node (referencing other products) it is considered to be a product group.

In situations where the product group id is added to the cart (in this example tshirt1), the product that ends up in the cart will be the first entry in the products Array (in this case tshirt1largeblack).

Attributes that are specified on the main product group cascade to the sub-products unless they are directly overriden on the sub-product.

If you want to add a specific sub-product to the cart, simply add it by id as normal.

// product group
{
  "dimensions": {
    "height": 4,
    "length": 30.48,
    "weight": 130,
    "width": 22.86
  },
  "fields": [
    {
      "attribute": true,
      "id": "size",
      "label": "Size"
    },
    {
      "attribute": true,
      "id": "color",
      "label": "Color"
    }
  ],
  "id": "tshirt1",
  "image": "https://demo.static.tools/media/images/composite-001-large-black.jpg",
  "name": "C&G Shirt",
  "price": 29,
  "products": [
    "tshirt1largeblack",
    "tshirt1largeblue",
    "tshirt1mediumblue"
  ]
},

// child product 1
{
  "attributes": {
    "size": "Large",
    "color": "Black"
  },
  "id": "tshirt1largeblack"
},

// child product 2
{
  "attributes": {
    "size": "Large",
    "color": "Blue"
  },
  "id": "tshirt1largeblue",
  "image": "https://demo.static.tools/media/images/composite-001-large-blue.jpg"
},

// child product 3
{
  "attributes": {
    "size": "Medium",
    "color": "Blue"
  },
  "id": "tshirt1mediumblue",
  "image": "https://demo.static.tools/media/images/composite-001-medium-blue.jpg",
  "price": 22
}
Last Updated: 1/9/2020, 1:57:21 AM