Events

Send what your contacts do in your own systems: an order placed or paid, a cart left behind, a product viewed. Each event is kept once, matched to the contact with its email address or phone number in your organization's default workspace, and shown on that contact's timeline. This route needs a key that holds events:write, which a key created before scopes existed does not hold.


POST/external/v1/events

Record events

The body is events, an array of 1 to 100 events. Every event is checked before any is kept: when one is refused, the request is refused and none of it is kept.

  • Name
    id
    Type
    string
    Description

    Required: your own id for the event, 1 to 128 characters without spaces, such as order-1001-paid. An event sent again with the same id is kept once, so a request can be sent again safely.

  • Name
    type
    Type
    string
    Description

    Required: what happened, one of the types below.

  • Name
    occurredAt
    Type
    string
    Description

    Required: when it happened, in ISO 8601, such as 2026-10-20T10:00:00Z. At most five minutes ahead of now, and at most 3,650 days ago.

  • Name
    email
    Type
    string
    Description

    The person's email address. Give it, the phone number or both.

  • Name
    phone
    Type
    string
    Description

    The person's phone number with its country code, such as +919812345678.

  • Name
    value
    Type
    number
    Description

    What the event was worth, from 0, with at most 14 integer digits and four decimal places, such as 1299.50. Give it with its currency. A customer.created event has none.

  • Name
    currency
    Type
    string
    Description

    The value's currency, as its ISO 4217 code, such as INR.

  • Name
    properties
    Type
    object
    Description

    The type's own details, as the table below allows them. Any other property is refused.

TypeWhat happenedIts properties
order.placedAn order was placedorderNumber, itemCount, productIds
order.paidAn order was paid fororderNumber, itemCount, productIds
order.fulfilledAn order was fulfilledorderNumber, itemCount, productIds
order.cancelledAn order was cancelledorderNumber, itemCount, productIds
order.refundedAn order was refundedorderNumber, itemCount, productIds
checkout.startedA checkout was starteditemCount, productIds
cart.abandonedA cart was left with items in ititemCount, productIds
product.viewedA product was viewedproductId
customer.createdThe person became a customerNone
  • orderNumber, productId and each id in productIds are 1 to 64 ASCII characters. Start with a letter, digit or #; the remaining characters may also use . _ : / -, such as #1001 or gid://shopify/Product/2.
  • itemCount is a whole number from 0 to 10,000, and productIds holds 1 to 50 ids.
  • Properties take at most 4 KB and accept only the identifiers and counts above. Do not put payment-card details, addresses or free text in them; identify the person through email and phone.

An order paid, and a cart left behind

curl -X POST https://api.oblic.app/external/v1/events \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {
        "id": "order-1001-paid",
        "type": "order.paid",
        "occurredAt": "2026-10-20T10:00:00Z",
        "email": "asha@example.org",
        "value": 1299.50,
        "currency": "INR",
        "properties": { "orderNumber": "#1001", "itemCount": 2, "productIds": ["SKU-1", "SKU-2"] }
      },
      {
        "id": "cart-7781",
        "type": "cart.abandoned",
        "occurredAt": "2026-10-20T11:30:00Z",
        "phone": "+919812345678",
        "properties": { "itemCount": 1, "productIds": ["SKU-3"] }
      }
    ]
  }'

Response

{
  "status": "success",
  "data": { "received": 2, "stored": 2, "duplicates": 0, "unmatched": 1 },
  "errors": null
}

The answer is 202:

  • stored is how many events were new and kept, and duplicates how many were kept already, by their id, and so not again.
  • unmatched is how many of those kept have no contact yet. An event is matched to the oldest contact of your default workspace with its email address, or else with its phone number as a phone or a WhatsApp number. One that matches no contact waits. When the matching service is enabled, it normally runs every ten minutes; a backlog or failure can delay matching. Events still unmatched 30 days after receipt are deleted by that service. An event never makes a contact.
  • A sub-account's events are sent with its X-Oblic-On-Behalf-Of, as its messages are (see Sub-accounts).
RefusedcdWhen
400UNKNOWN_EVENT_TYPEAn event's type is not one of the types
400PERSON_REQUIREDAn event gives neither email nor phone
400INVALID_VALUEA value without its currency or a currency without a value, a value below 0, of more than 14 integer digits or with more than four decimal places, or a value on a customer.created event
400INVALID_PROPERTIESA property the type does not have, or one not of its shape
400INVALID_OCCURRED_AToccurredAt is more than five minutes ahead of now, or more than 3,650 days ago
400the field, such as EVENTS[0].IDevents is missing, empty or longer than 100, or a field is missing or not of its shape
403INSUFFICIENT_SCOPEThe key does not hold events:write

Refusals identify the field or event's array position, such as events[2].type, rather than echoing its email address, phone number or property values. Unknown property names can appear in the explanation, so do not put sensitive information in names either. Shape validation runs before the type-specific checks; a response lists the problems found at that validation stage.


Start a journey

A journey made in Journeys can start on what a contact does when the journey runtime is enabled for your workspace. In its editor, choose Does something in your store as what starts it, then the type of event. To narrow it, add the products the event must name, by the ids your store sends, and the least value it must be worth, with its currency.

  • Once for each event: a contact who pays for two orders starts the journey twice, while an event sent again with the same id starts it once.
  • Only a recent event: an event starts journeys when it is kept with its contact, or later matched to one, within 24 hours of its occurredAt. One from further back, such as a backfill of past orders, shows on the timeline and counts for segments, but starts no journey.
  • Products and value: products match an order's, a checkout's or a cart's productIds, or the productId viewed, and a least value matches an event worth at least that much in that currency. A customer.created event has neither, so neither narrows it.

From Shopify

When the Shopify integration and its installation link are configured, connect a store from Settings → Integrations → Shopify store: install Oblic's app in Shopify, then connect the store to your organization. If the integration is unavailable, ask your administrator to configure it first. Its orders then become events of the types above, matched to your contacts by email address or phone number as the events you send are. Customers who subscribe to your email or SMS marketing become contacts with that consent.

From ShopifyThe event
An order placed, paid, fulfilled or cancelledorder.placed, order.paid, order.fulfilled, order.cancelled
A refundorder.refunded, for the person the order was placed by, worth what was refunded
A checkout with an email address or phone numbercheckout.started
A checkout an hour idle with no ordercart.abandoned, once for each checkout
A customer who subscribes to your marketing and is not yet a contactcustomer.created, as Oblic makes them one
  • What an event holds: the order's value in your store's currency, its number, its item count and its products, by Shopify's product ids. Nothing else of the order is kept.
  • Customers who subscribe: a customer who subscribes to your email or SMS marketing in Shopify is found among your contacts as an event's person is, or else made a contact of your default workspace, named by their address or number, and that consent is recorded on the address or number. A customer who has not subscribed is never made a contact.
  • Unsubscribing: a customer who unsubscribes in Shopify is unsubscribed from your email, or sent no more SMS from your campaigns, automations and journeys, until they subscribe there again. An email unsubscribe made in Oblic, such as from an email's link, is never undone from Shopify.
  • Disconnecting: disconnect a store from the same page, then uninstall Oblic's app in Shopify. Disconnecting keeps its events. The store and its events are deleted when Shopify's later shop/redact request is processed, not by disconnecting alone.
  • Customers' privacy: when Shopify asks Oblic to delete a customer's data, their events from that store go, and when their consent was recorded on a contact, your organization's owners are told in Oblic, to delete the contact; when a customer asks for their data, your organization's owners are told in Oblic.
Was this page helpful?