Products

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

Mandatory fields

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

Field	Type	Description
external_id	string	An identifier which uniquely identifies the product.
price	money	Base price of the product in cents. A price of 10.50 € should be passed as 1050.

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.

Field	Type	Description
type	string	Product type, e.g. CD or T-Shirt.
category	string or list of string	Visible name of the category, e.g. Bedding, Jazz or Men's Knitwear.
category_id	string or list of string	Your technical name or id for the category.
vendor	string	Publisher or manufacturer of a product, e.g. L'Oréal.
ean	string	International Article Number of the product. An identifier which uniquely identifies the product. In case product imports from another source do not contain a product_id, Custobar will try to look for sku or ean field to connect the product update with.
sku	string	An identifier which uniquely identifies the product. In case product imports from another source do not contain a product_id, Custobar will try to look for sku or ean field to connect the product update with.
shop_id	string	Name or identifier for the shop in which the product is available. This field can then be used to only show a specific shops products in the email editor.
brand	string	Name of the brand, e.g. Escada Home, Gucci or Miles Davis.
title	string	Name of the product, e.g. Egyptian Cotton Linen Fitted Sheet.
image	string	Persistent address to a product image. The image may be cached or served through a proxy during marketing campaigns.
date	datetime	The date, when the product has been modified most recently, e.g. 2016-06-08 or 2016-06-10T14:10:00Z. If the timezone is not given, the timezone will be defaulted to the timezone configured in the Custobar's settings.
url	string	Address of a product page. This field is used to provide link to a web page in campaign mails.
sale_price	money	Advertised sale price of the item in cents, if the product is in sale, e.g. for a sale price of 9.45 €, pass 945.
lowest_price	money	Lowest price of the item in the past 30 days the item in cents. This field is related to EU's Omnibus directive.
price_before_campaign	money	Price of the item in cents before a long-term campaign that lasts more than 30 days but less than 60 days, and where the price progressively decreases. This field is related to EU's Omnibus directive.
highest_price	money	Highest price of the item in the past 30 days the item in cents. This field is related to EU's Omnibus directive.
description	string	Description is embedded into marketing templates as text.
language	language_code	Language of given product information. See section "Localizing product data".
visible	boolean	Determines whether a product is "active". Products that are end-of-life, should be marked as not visible. If omitted, defaults to true.
exclude_from_recommendations	boolean	A master flag determining whether the product may appear in product recommendations. If omitted, defaults to true.
recommendation_set_ids	list of string	A list of external_ids that that belong to same recommendation set. When generating recommendations, only the highest-ranking recommendation from the set is used. Up to 20 external_ids can be provided for the set.
in_stock	boolean	Indicates whether the product is currently stocked in general.
stock	list of object	Shop specific stock status. A list of objects containing keys shop_id and quantity, e.g. [{"shop_id": "east-london", "quantity": 5}]. The key shop_id is the external_id of the imported shop.
tags	[set][] of string	Tags assigned for this product.
main_product_ids	list of string	A list of external_ids of products that are considered to be the main products. I.e. if you have shirts with different sizes, define the main_product_ids for the product variants that refer the main product.

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

Field	Type	Description
unit	string	Plural shorthand for units sold, e.g. l, oz or pcs.
weight	string	Weight of one sold unit. For product bundles or multi-packs, the weight is the combined weight of items sold in one bundle.

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:

json

{
    "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:

json

{
    "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.

csv

external_id;stock.0.shop_id;stock.0.quantity11912;hki;1411912;tku;011912;hml;8

Examples

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

bash

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.

json

{
    "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.

json

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

Products ​

Mandatory fields ​

Optional fields ​

Company-specific fields ​

Product variants ​

Localizing product data ​

Stock quantities ​

Examples ​

Products

Mandatory fields

Optional fields

Company-specific fields

Product variants

Localizing product data

Stock quantities

Examples