Sending Past Events

If you have migrated from another service or just created an account in our platform, and you have a history of

• offline orders,
• contact activity,
• subscriptions,
• or other events you want to use for advanced segmentation,

you can transfer the available data from your CRM or other data store to our system via the API resource Generate past events.

📘

Important

Before importing events, enable segmentation for the types of events you want to download.

If your tariff plan does not include segmentation by events, please submit a request to [email protected]

How to set up segmentation by events

To assign events to contacts, pre-import the contact database to your account.

For example, you have a certain number of orders over the past year, and you want to build a segment with customers interested in a certain type of products or services, get statistics on the average order value, or segment contacts by geodata (if applicable).

Convert these orders into a JSON format supported for API according to the specification, and send them to the system. You can send an array of up to 500 such events within one request. Specify the time of each event in the field occurred:

• format of date: YYYY-MM-DD;
• format of date with the time: YYYY-MM-DDThh:mm:ss±hh:mm.

🚧

Important

• The date event parameter must be passed in the ISO 8601 format with a specified time zone offset relative to UTC. For example: 2025-01-05T13:00:00+02:00, where +02:00 indicates that the local time is 2 hours ahead of UTC.
• Note that some countries observe daylight saving time (DST), which may affect the offset.

For example, you send an order of two mobile devices bought at a few years interval:

{
  "events": [
    {
      "eventTypeKey": "orderCreated",
      "keyValue": "test_v3_event_1",
      "params": {
        "phone": "380501234789",
        "externalOrderId": "12345679102",
        "externalCustomerId": "AA1100",
        "totalCost": "258.0",
        "status": "INITIALIZED",
        "date": "2025-01-05T13:00:00+02:00",
        "currency": "UAH",
        "items": [
          {
            "externalItemId": "200600",
            "name": "Super Device",
            "category": "devices",
            "quantity": 2,
            "cost": 999,
            "url": "http://example.com/item/200600",
            "imageUrl": "http://example.com/item/200600/image.png",
            "description": "High quality"
          }
        ]
      },
      "occurred": "2025-02-04T12:00"
    },
    {
      "eventTypeKey": "orderCreated",
      "keyValue": "test_v3_event_1",
      "params": {
        "phone": "380500000001",
        "externalOrderId": "12345679103",
        "externalCustomerId": "AA1111",
        "totalCost": "258.0",
        "status": "INITIALIZED",
        "date": "2025-01-07T13:00:00+02:00",
        "currency": "UAH",
        "items": [
          {
            "externalItemId": "200600",
            "name": "Super Device",
            "category": "devices",
            "quantity": 2,
            "cost": 999,
            "url": "http://example.com/item/200600",
            "imageUrl": "http://example.com/item/200600/image.png",
            "description": "High quality"
          }
        ]
      },
      "occurred": "2025-02-07T16:00"
    }
  ]
}

📘

Note

Historical events uploaded via Generate past events are displayed in Event history but not in the Orders section — it shows only order events passed through the standard mechanisms, such as Add orders.

📘

Processing and request rate

Events are processed asynchronously, and the processing order is not guaranteed. For historical data, the reference point is the time passed inside the event itself (the occurred field), not the order in which requests are processed.

Generate past events accepts up to 100 requests per second, while Generate event accepts up to 350. See Rate limits for the full list.

Apart from basic fields with the name, price, and link to a product, you can send any related data that is available to build segments. For example, you can send the country and city of the buyer to use for segmentation by geolocation.

{
  "city": "Los Angeles",
  "country": "USA"
}

Based on the available datasets you can build dynamic segment:

You can also delete old or irrelevant events. To do this, send a request to the same resource, but using the method type DELETE. The time range is mandatory — specify it in the request body:

{
  "from": "2019-06-04T10:47",
  "to": "2020-01-04T13:33"
}

Both bounds are inclusive. Since the 2026 update, the endpoint accepts an exact time in UTC, not just a date.

The DELETE method is inactive by default. To activate it, please contact our support team.

📘

Scope, limits, and behavior

• The method removes only historical events that were previously uploaded through past_events. Regular v2/v3 events and orders are not removed by it — there is no way to delete them on request; they are cleared automatically once their retention period expires.
• The published rate limit is 5 requests per second.
• If the feature is not enabled for your organization, the endpoint returns 403 with a message stating that the organization is not enabled for events removing.
• Processing is asynchronous and has no fixed SLA — the underlying cleanup can start several hours after the request, so events are not removed the moment the response arrives.
• There is no maximum date range or maximum number of events per request. To reduce processing load, delete a continuous period with one request covering the whole range rather than many small per-day requests.
• If some data has already aged out of the main storage under its TTL, the method does not remove it from segmented history.
• The maximum range and the maximum number of events per request are not defined.