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.
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 itscurrency. Acustomer.createdevent 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.
| Type | What happened | Its properties |
|---|---|---|
order.placed | An order was placed | orderNumber, itemCount, productIds |
order.paid | An order was paid for | orderNumber, itemCount, productIds |
order.fulfilled | An order was fulfilled | orderNumber, itemCount, productIds |
order.cancelled | An order was cancelled | orderNumber, itemCount, productIds |
order.refunded | An order was refunded | orderNumber, itemCount, productIds |
checkout.started | A checkout was started | itemCount, productIds |
cart.abandoned | A cart was left with items in it | itemCount, productIds |
product.viewed | A product was viewed | productId |
customer.created | The person became a customer | None |
orderNumber,productIdand each id inproductIdsare 1 to 64 ASCII characters. Start with a letter, digit or#; the remaining characters may also use. _ : / -, such as#1001orgid://shopify/Product/2.itemCountis a whole number from 0 to 10,000, andproductIdsholds 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
emailandphone.
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:
storedis how many events were new and kept, andduplicateshow many were kept already, by theirid, and so not again.unmatchedis 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).
| Refused | cd | When |
|---|---|---|
| 400 | UNKNOWN_EVENT_TYPE | An event's type is not one of the types |
| 400 | PERSON_REQUIRED | An event gives neither email nor phone |
| 400 | INVALID_VALUE | A 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 |
| 400 | INVALID_PROPERTIES | A property the type does not have, or one not of its shape |
| 400 | INVALID_OCCURRED_AT | occurredAt is more than five minutes ahead of now, or more than 3,650 days ago |
| 400 | the field, such as EVENTS[0].ID | events is missing, empty or longer than 100, or a field is missing or not of its shape |
| 403 | INSUFFICIENT_SCOPE | The 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
idstarts 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 theproductIdviewed, and a least value matches an event worth at least that much in that currency. Acustomer.createdevent 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 Shopify | The event |
|---|---|
| An order placed, paid, fulfilled or cancelled | order.placed, order.paid, order.fulfilled, order.cancelled |
| A refund | order.refunded, for the person the order was placed by, worth what was refunded |
| A checkout with an email address or phone number | checkout.started |
| A checkout an hour idle with no order | cart.abandoned, once for each checkout |
| A customer who subscribes to your marketing and is not yet a contact | customer.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/redactrequest 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.