« Back to API reference

Importing data into Custobar

Custobar has five standard 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 – Sale 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.


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 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 escape sequences, or encoded in UTF-8.


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:

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:

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",
        "breed": "arabian",
        "color": "chestnut"

can be imported using CSV file like this (semi-colon delimited this time)


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


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.


curl -X POST -u USER -H "Content-Type: application/json" \
  --data-binary @customers.json \


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


curl -X POST -u USER -H "Content-Type: application/json" \
  --data-binary @products.json \


curl -X POST -u USER -H "Content-Type: application/json" \
  --data-binary @shops.json \


curl -X POST -u USER -H "Content-Type: application/json" \
  --data-binary @sales.json \

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 support.