« Back to API Documentation

Importing data into Custobar

Custobar has five different types of data.

  • Customers - Usually your registered customers or customers from your loyality program
    if you have one.
  • Events - Customer events, such as email subscriptions, browsing products online and
    participation in competitions.
  • Products - Product catalog.
  • Shops - Brick-and-mortar locations and e-commerce sites.
  • Sales - Sales order items.

The identifying fields of the five data types, such as external_id of the customer, are free
form strings that can be defined by you.

Data formats

The most versatile data format for importing data to Custobar is Json, but also CSV (comma-separated-values)
is supported. When uploading data using the Custobar API, the format of the data must be specified using
the HTTP Content-Type header.

Json

When importing data in Json, the data items are send in a list, optionally wrapped in a Json object’s
property with name corresponding to the type of data being imported. Here is an example of valid
product import, importing two products, using the unwrapped list style:

[
    { "external_id": "P001-01", "title": "Unicorn T-Shirt, Pink" },
    { "external_id": "P001-02", "title": "Unicorn T-Shirt, White" }
]

And the same using Json object wrapper:

{
    "products": [
        { "external_id": "P001-01", "title": "Unicorn T-Shirt, Pink" },
        { "external_id": "P001-02", "title": "Unicorn T-Shirt, White" }
    ]
}

The proper HTTP content type header for importing JSON is “application/json”:

Content-Type: application/json

The assumed character encoding for Json in utf-8, as dictated by Json specification. If the string values in
the data contain non-ascii characters, they should be either escaped using valid Json’s ecape sequences,
or encoded in utf-8.

CSV

The proper HTTP content type header for iporting CSV data is “text/csv”. Optinally, character set may be
given in the header. Supported charsets are “utf-8”, “utf-16” and “iso-8859-1” (latin-1). If not given, character
encoding defaults to utf-8. To import latin-1 encoded data, use:

Content-Type: text/csv; charset=iso-8859-1

Delimiter character for data fields can be either comma (“,”), semicolon (“;”) or tabulator (”\t”).
Custobar will infer the correct delimiter to use from the data.

The first line of the CSV file should be the header line listing all column names. Here is the product
import example using (comma delimited) CSV:

external_id,title
P001-01,"Unicorn T-Shirt, Pink"
P001-02,"Unicorn T-Shirt, White"

Note that the title values that contain delimiter characters or newline characters must be quoted using
double quotes. It is ok to quote all values even if not strictly required. Because double quotes
function as escape characters, they need to be escaped as well. The CSV escape for double quote character
is double double quote. For example, importing a product with quotes in title:

external_id,title
s06e07,"Episode 7: ""Once More, With Feeling"""

Nested data in CSV

Because a CSV does not support nested data types, importing nested objects can be a little tricky. It is
however possible, using dot-separated property paths. For example, this customer import with nested structure:

{
    "customers": [
        "external_id": "c001",
        "email": "cge@example.com",
        "horse": {
            "name": "Käthy",
            "color": "chestnut"
        }
    ]
}

can be imported using CSV file like this (semicolon-delimited this time):

external_id;email;horse.name;horse.color
c001;cge@example.com;Käthy;chestnut

Json lists can be encoded using integer indices in the property paths. For example, importing the stock amount
for a product in a single location:

external_id;stock.0.shop_id;stock.0.quantity
P001-01;1;39

This will be treated as the Json structure below:

[
    {
        "external_id": "p001-01",
        "stock": [
            {
                "shop_id": "1",
                "quantity": "39"
            }
        ]
    }
]

Note that the numerical property values are converted to Json strings. They will be interpreted as numbers
as appropriate when validating the data against the data schema.

File transfer

To import your data to Custobar, you can use the Custobar API. Below are examples using curl to upload
the data.

In all the examples below, replace mycompany with your company name as it is used in your company’s
Custobar app.

Customers

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

Events

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

Products

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

Shops

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

Sales

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

Secure FTP

It’s also possible to use sftp to transfer the files. Files are transferred to directory
/srv/sftp/mycompany/tocustobar on your Custobar server.

For further details, please contact Custobar technical assistance.