API documentation

Events

Written by Custobar | Jun 12, 2024 4:10:14 PM

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

Event types

Type Description
BROWSE A generic browsing event, see the required supplemental fields below.
MAIL_SUBSCRIBE Add email marketing permission for given customer. If no customers are found with the given email address new customer will be created.
MAIL_UNSUBSCRIBE Unsubscribe customer from the email list.
ORDER_SHIPPED An order related to a sale has been shipped. You may supply sale_id and tracking_number, if you want to identify the shipment and the associated sale.
BASKET_ADD Product added to shopping basket. Identify the product added with product_id key, with the identifier of your product.
SENTIMENT Customer satisfaction survey result. Whenever the customer responds to a customer satisfaction survey, you may send this event with key sentiment_value, being an integer.
SMS_SUBSCRIBE Add sms marketing permission for given customer. If no customers are found with the given phone number new customer will be created.
SMS_UNSUBSCRIBE Turns off SMS marketing permission for the customer

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

Common fields

Mandatory fields

Field Type Description
type string The event type in capital letters, see the table above for possible event types.
date datetime Date of the event, e.g. 2015-08-28 or 2015-08-28T14:10:00Z. If the timezone is not given, the timezone will be defaulted to the timezone configured in the Custobar's settings.

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.

Event Field Type Description
BROWSE label string A label that you've assigned to the particular page, and/or
BROWSE product_ean string the EAN for the product, and/or
BROWSE product_id string identifier of the product being browsed that is stored in Custobar, and/or
BROWSE path string the browsed path, and/or
BROWSE utm_campaign string the UTM tag associated with this browse.
MAIL_SUBSCRIBE mailing_lists list of string List of email list names to subscribe.
MAIL_UNSUBSCRIBE mailing_lists list of string List of email list names to unsubscribe from. To unsubscribe from all lists, use a special list name _ as the singular element in the list.
ORDER_SHIPPED tracking_number string Tracking number provided by the shipping company.
SENTIMENT sentiment_value integer The sentiment value as an integer, usually a number between 0 and 10, bounding values included.

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.

Field Type Description
reason string A string providing additional information related to the event for the Custobar users.
source string A string designating the source of the event, e.g. "unsubscribe form" or "service desk".
utm_campaign string A campaign identifier, which this event is a part of.
utm_medium string A medium through which the event came through.
utm_content string A content piece related to the event.
utm_source string The UTM source of an event.
tags [set][] of string Tags assigned for this 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
}
}