Products

A product represents a single sellable item. Each product is defined by a set of mandatory, optional and company-specific custom fields.

Common fields

Mandatory fields

A product record must contain in minimum two fields, the identifier, which you use to refer the product and a price.

Optional fields

Optional fields are not required, but recommended, since they add more richness for Custobar users, thus allowing them to make better marketing decisions.

In addition to recommended optional fields, you may describe the product further by defining its unit of sale and item weight.

Company-specific fields

You may add additional fields, that are company specific by prefixing them with a company short name and a double underscore __, e.g. COMPANY__color.

Company specific fields are searchable in the Custobar user interface.

Product variants

Suppose you sell clothes and have different sizes for each product. To create a relation between the main product and the size variants, define main_product_ids in the individual shirt products that represent the products in given size.

Localizing product data

Product data can be localized into differed languages by supplying information for the same product multiple times (same external_id), but translating the relevant fields and the changing the language code to the appropriate language.

Stock quantities

Available stock per location can be specifed as a list of shop_id/quantity pairs under the stock property. For example, specifying the available stock for a product at three shops:

{
  "products": [
    {
      "external_id": "11912",
      "stock": [
        { "shop_id": "hki", "quantity": 14 },
        { "shop_id": "tku", "quantity": 0 },
        { "shop_id": "hml", "quantity": 8 }
      ]
    }
  ]
}

When updating stock data, the incoming data is merged by the shop_id, so the entries that are not explicitly given in new data are not erased. For example, after updating the stock state above with the following import:

{
  "products": [
    {
      "external_id": "11912",
      "stock": [
        { "shop_id": "hki", "quantity": 9 },
        { "shop_id": "lpr", "quantity": 1 }
      ]
    }
  ]
}

the quantities are: hki:9, tku:0, hml:8, lpr:1.

When importing data using CSV, stock quantities can be updated using the property path notation, e.g.

external_id;stock.0.shop_id;stock.0.quantity
11912;hki;14
11912;tku;0
11912;hml;8

Examples

To upload new or changed product information, you may pass them to Custobar using a HTTP POST command, e.g.

curl -X POST -u USER -H "Content-Type: application/json" \
    --data-binary @products.json https://COMPANY.custobar.com/api/products/upload/

Basic product import

The product objects must be provided as a list, wrapped into a JSON object, with a key products, as shown in the example below.

{
  "products": [
    {
      "external_id": "1619490226",
      "category": "Children's Books",
      "category_id": "1619",
      "title": "Alice in Wonderland",
      "date": "2013-02-13T13:10:40Z",
      "url": "https://www.example.com/product/1619490226",
      "brand": "Lewis Carroll",
      "type": "Paperback",
      "price": 1200,
      "stock": [
        {"shop_id": "BAKER-STREET", "quantity": 40},
        {"shop_id": "CANNON-STREET", "quantity": 17}
      ],
      "COMPANY__author": "Lewis Carroll",
      "COMPANY__publisher": "Empire Books",
    },
    {
      "external_id": "1770461221",
      "category": ["Children's Books", "Nordic Classics"],
      "category_id": ["1619", "1311"],
      "title": "Moomin and the Comet",
      "date": "2011-12-10T08:10:42Z",
      "url": "https://www.example.com/product/1770461221",
      "brand": "Tove Jansson",
      "type": "Paperback",
      "price": 2080,
      "recommendation_set_ids": ["1619490226"],
      "COMPANY__author": "Tove Jansson",
      "COMPANY__publisher": "Drawn and Quarterly"
    }
  ]
}

Product with variants where main product also has a price defined

To import a product which has variants, use the main_product_ids array to define the relationship as shown below. In the example below, the first product is a master product that also includes a price. This price can be a "starting at" sort of price if the variants pricing varies a lot. After the main product there are three subsequent variant products.

{
  "products": [
    {
      "external_id": "5789422",
      "title": "Vintage t-shirt",
      "type": "T-shirt",
      "price": 1995
    },
    {
      "external_id": "5789422LG",
      "title": "Vintage t-shirt - Large",
      "main_product_ids": ["5789422"],
      "price": 1995
    },
    {
      "external_id": "5789422MD",
      "title": "Vintage t-shirt - Medium",
      "main_product_ids": ["5789422"],
      "price": 1995
    },
    {
      "external_id": "5789422SM",
      "title": "Vintage t-shirt - Small",
      "main_product_ids": ["5789422"],
      "price": 1995
    }
  ]
}