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.

Field Type Description
external_id String SKU or an equivalent identifier which uniquely identifies the product.
price Integer (Price in cents) 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 Array of Strings Visible name of the category, e.g. Bedding, Jazz or Men's Knitwear.
category_id String or Array of Strings 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.
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 URL String Persistent address to a product image. The image may be cached or served through a proxy during marketing campaigns.
date ISO8601 String 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 URL String Address of a product page. This field is used to provide link to a web page in campaign mails.
sale_price Integer (Price in cents) 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.
description String Description is embedded into marketing templates as text.
language ISO639-1 String Language of given product information. See section "Localizing product data".
visible Bool 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 Bool A master flag determining whether the product may appear in product recommendations. If omitted, defaults to true.
recommendation_freq_days Integer An integer, determining how often a product can be recommended. If the value is negative, the product can recommended only once. The value is zero or the field is omitted, the product can be recommended always. If the value is greater than zero, the product can be recommended for every n days.
recommendation_set_ids Array of Strings 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 Bool Indicates whether the item is currently in stock.
main_product_ids Array of Strings 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.

Example

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/

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