Products

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 Demoopen in new window.

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.jsonopen in new window 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
  }
}

Variants

Product Variants allow the user to select from within a set of products that are differentiated by their attributes.

A product that contains a variants node (referencing other products) is considered to be a variant group.

All values specified on the variant group cascade as defaults to the child variants.

If the variant group id is added to the cart (e.g. tshirt1), it automatically resolves to the first child in the variants (in this case tshirt1largeblack).

Specific variants can be added to the cart directly by id, or by supplying the id of the variant group, (or any of the variants), along with field selections.

// variant 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/variant-001-large-black.jpg",
  "name": "C&G Shirt",
  "price": 29,
  "variants": [
    "tshirt1largeblack",
    "tshirt1largeblue",
    "tshirt1mediumblue"
  ]
},

// variant 1
{
  "attributes": {
    "size": "Large",
    "color": "Black"
  },
  "group": "tshirt1",
  "id": "tshirt1largeblack"
},

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

// variant 3
{
  "attributes": {
    "size": "Medium",
    "color": "Blue"
  },
  "group": "tshirt1",
  "id": "tshirt1mediumblue",
  "image": "https://demo.static.tools/media/images/variant-001-medium-blue.jpg",
  "price": 22
}

# Products

# Definition

# Inventory JSON

# Attributes

# description

# digital

# dimensions

# fields

# Field Types

# Field Notes

# id

# image

# name

# price

# quantity

# sku

# Examples

# Digital Only

# Physical

# Configurable

# Delta Priced

# Fractional

# Variants