Events

An event is an action performed by a customer, such as browsing a product page or subscribing to a newsletter.

Event types

Additional company specific event types can be specified in the Custobar advanced settings page.

Common fields

Mandatory fields

The customer generating the event is identified by supplying at least one of the customer identifying fields customer_id, phone_number, email or customer_token. Where customer_token is the same as cb_token in customer data.

Depending on the event type, some additional fields are required.

The products listed in the events are linked to the products in Custobar's database by matching the product_id in the event to the external_id of the imported products.

If there is no product in the database matching the product_id of the incoming event, a product with that ID will be created along with the event, and the details listed in the event (title, price, etc.) will be copied to that new product.

In case a product_id is not included in the event, Custobar tries to find a matching product using the sku and ean fields instead, and link the event to that product.

If the event does not include product_id, but includes a sku or ean, but a matching product is not found, Custobar will create the product, but it will give it a synthetic external_id, composed of the ean/sku in the event. Note however, that if the product matching that sku/ean is later imported to Custobar, it won't be matched to this product with the synthetic id. So, if the system that is importing events to Custobar does not have access to the proper product_ids, it can use ean/sku instead to identify the event. But, in this case, it's important to import the products first, so that the matching products will be found at the events import time.

Optional fields

In addition to mandatory fields, you may provide additional fields that provide more information on the event.

The following customer fields may also be provided together with the event data:

• first_name
• last_name
• street_address
• zip_code
• country
• language

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

Company specific fields are searchable in the Custobar user interface.

Example

To upload events, 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 @events.json https://COMPANY.custobar.com/api/events/upload/

The events must be provided as a list of objects, each object containing the information of a single event.

[
  {
    "type": "BROWSE",
    "date": "2016-10-25T12:50:19Z",
    "product_id": "9000",
    "customer_id": "23132",
    "utm_source": "partner-a",
    "COMPANY__loyalty_level": "platinum"
  },
  {
    "type": "MAIL_SUBSCRIBE",
    "date": "2016-10-25T12:51:29Z",
    "email": "john.doe@example.org",
    "mailing_lists": ["carpentry", "new_products"]
  },
  {
    "type": "MAIL_UNSUBSCRIBE",
    "date": "2016-10-25T13:00:19Z",
    "email": "jane.doe@example.org",
    "mailing_lists": ["new_products"]
  },
  {
    "type": "ORDER_SHIPPED",
    "date": "2016-10-30T12:04:51Z",
    "email": "jane.doe@example.org",
    "sale_id": "20140980234098",
    "COMPANY__tracking_number": "JJFIFAKE234082984"
  }
]

Deleting events

To delete events from Custobar, you have a couple of options.

Option 1:

Start by fetching the IDs for the events you want to delete from Custobar using our data retrieval API.

Once you have the IDs you can delete them by importing them in this exact form:

[
    {
        "id": 1249013,
        "is_deleted": true
    },
    {
        "id": 41939,
        "is_deleted": true
    }
]

Option 2:

You can also make a request directly to our data query API https://COMPANY.custobar.com/api/data/query/ to delete a specific set of events based on specific conditions.

The example below would delete all BASKET_ADD events without a product_id from your Custobar environment.

 POST /api/data/query/

{
    "datatype": "events",
    "match": {
        "type": "BASKET_ADD",
        "product_id.exists": false
    },
    "update": {
        "is_deleted": true
    }
}