API reference

Automation events

Report what happened in a store or site; the account decides in the console what message follows.

Push an event#

POST/v1/automation_eventsScopeevents:write

Reports that something happened in a store or site. The account decides in the console what follows from it: the enabled automations of the source for this event type are matched, the recipient and consent are checked, and the messages are scheduled (occurred_at plus the delay of each automation, outside its quiet hours).

Authenticate with the source key, or with an API key that has events:write and name the source in source.

The event id is the idempotency key: a second request with the same id for the same source within 30 days returns the first receipt with status: "duplicate", HTTP 200 and Idempotent-Replayed: true, whatever its body. An Idempotency-Key header is accepted and ignored.

202 does not depend on the balance. Billing happens when a message is sent, as for POST /v1/messages; a run that cannot be paid for fails with insufficient_balance. Retry only transport errors, 429 and 5xx.

Request body

idstringRequired
Unique per source for one real-world occurrence: the idempotency key of the event. Build it from stable parts (<platform>:<object>:<object id>:<type>:<sequence>), never from the time of the send attempt.
1 to 255 characters
typestringRequired
One of the documented event types, or custom.<name> with a name of lower-case letters, digits, dots and underscores (up to 64 characters).
occurred_attimestampRequired
When it happened at the source. Delays of automations are measured from this instant. Older than 7 days: stored and ignored (stale). More than 10 minutes ahead: 400.
sourcestringOptional
The integration source the event belongs to (src_…). Required with an API key, refused with a source key.
testbooleanOptional
A test send from a plugin: automations run without delay and quiet hours, and the event is left out of the statistics.
siteobject or nullOptional
The store or site. Falls back to the name and URL of the source.
Show child attributesHide child attributes
- namestring or nullOptional
  Name.
  Up to 255 characters
- urlstring or nullOptional
  Address.
customerobject or nullOptional
Optional for events addressed to the account owner only.
Show child attributesHide child attributes
- idstring or integer or nullOptional
  The platform's customer ID.
- namestring or nullOptional
  Full name. Built from first and last name when omitted.
  Up to 255 characters
- first_namestring or nullOptional
  First name.
  Up to 120 characters
- last_namestring or nullOptional
  Last name.
  Up to 120 characters
- phonestring or nullOptional
  Phone number in E.164 format. A number in another format is normalised like phone_raw.
  Up to 40 characters
- phone_rawstring or nullOptional
  The number as the customer typed it. Read as a national number of country (then of the account's country) when phone is not E.164.
  Up to 60 characters
- emailstring or nullOptional
  Email address.
  Up to 254 characters
- localestring or nullOptional
  BCP 47 language tag. Selects the language variant of the automation.
  Up to 35 characters
- countrystring or nullOptional
  ISO 3166-1 alpha-2 country code.
  Up to 2 characters
- consentobject or nullOptional
  What the customer agreed to, as the source knows it.
  Show child attributesHide child attributes
  transactionalboolean or nullOptional
  true, false, or null for unknown.
  marketingboolean or nullOptional
  true, false, or null for unknown. Marketing automations need true.
  channelsobjectOptional
  Per channel type; wins over the two flags for that channel.
  sourcestring or nullOptional
  Where the consent came from, for example checkout_checkbox.
  Up to 120 characters
  collected_atstring or nullOptional
  When it was collected (ISO-8601).
orderobject or nullOptional
Show child attributesHide child attributes
- idstring or integerRequired
  The platform's order ID.
- numberstring or integer or nullOptional
  The order number customers see.
- statusstring or nullOptional
  Current status on the platform.
  Up to 64 characters
- previous_statusstring or nullOptional
  Status before the change.
  Up to 64 characters
- currencystring or nullOptional
  ISO 4217 code.
  Up to 3 characters
- totalobject or nullOptional
  Order total.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
- subtotalobject or nullOptional
  Subtotal.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
- shipping_totalobject or nullOptional
  Shipping.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
- discount_totalobject or nullOptional
  Discounts.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
- itemsarray of objectsOptional
  Line items.
  Show child attributesHide child attributes
  idstring or integer or nullOptional
  Product ID.
  namestring or nullOptional
  Product name.
  Up to 500 characters
  skustring or nullOptional
  SKU.
  Up to 255 characters
  quantitynumber or nullOptional
  Quantity.
  unit_priceobject or nullOptional
  Price of one unit.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
  urlstring or nullOptional
  Product page.
  image_urlstring or nullOptional
  Product image.
- items_countnumber or nullOptional
  Number of units.
- items_summarystring or nullOptional
  Line items as one line of text, for example 2 × Mug.
  Up to 2000 characters
- payment_methodstring or nullOptional
  Payment method code.
  Up to 120 characters
- payment_method_titlestring or nullOptional
  Payment method as the customer sees it.
  Up to 255 characters
- shipping_methodstring or nullOptional
  Shipping method.
  Up to 255 characters
- trackingobject or nullOptional
  Shipment tracking.
  Show child attributesHide child attributes
  numberstring or nullOptional
  Tracking number.
  Up to 255 characters
  urlstring or nullOptional
  Tracking page.
  carrierstring or nullOptional
  Carrier.
  Up to 120 characters
- status_urlstring or nullOptional
  Where the customer can follow the order.
- notestring or nullOptional
  Note to the customer.
  Up to 4000 characters
- created_atstring or nullOptional
  When the order was placed (ISO-8601).
cartobject or nullOptional
Show child attributesHide child attributes
- idstring or integerRequired
  Stable ID of the cart or checkout. A later event with the same ID replaces the pending reminder; an order carrying it in data.cart_id cancels it.
- currencystring or nullOptional
  ISO 4217 code.
  Up to 3 characters
- totalobject or nullOptional
  Cart total.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
- itemsarray of objectsOptional
  Line items.
  Show child attributesHide child attributes
  idstring or integer or nullOptional
  Product ID.
  namestring or nullOptional
  Product name.
  Up to 500 characters
  skustring or nullOptional
  SKU.
  Up to 255 characters
  quantitynumber or nullOptional
  Quantity.
  unit_priceobject or nullOptional
  Price of one unit.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
  urlstring or nullOptional
  Product page.
  image_urlstring or nullOptional
  Product image.
- items_countnumber or nullOptional
  Number of units.
- items_summarystring or nullOptional
  Line items as one line of text.
  Up to 2000 characters
- recovery_urlstring or nullOptional
  Link that restores the cart.
- updated_atstring or nullOptional
  Last cart activity (ISO-8601).
formobject or nullOptional
A form submission.
Show child attributesHide child attributes
- pluginstring or nullOptional
  Form plugin.
  Up to 120 characters
- idstring or integer or nullOptional
  Form ID.
- namestring or nullOptional
  Form name.
  Up to 255 characters
- fieldsobjectOptional
  Label → value.
- fields_summarystring or nullOptional
  The fields as text, one per line.
  Up to 8000 characters
- page_urlstring or nullOptional
  Page the form is on.
appointmentobject or nullOptional
An appointment.
Show child attributesHide child attributes
- idstring or integerRequired
  Appointment ID.
- servicestring or nullOptional
  Service.
  Up to 255 characters
- starts_atstring or nullOptional
  Start (ISO-8601).
- ends_atstring or nullOptional
  End (ISO-8601).
- timezonestring or nullOptional
  IANA time zone of the appointment.
  Up to 64 characters
- locationstring or nullOptional
  Where.
  Up to 500 characters
- staffstring or nullOptional
  With whom.
  Up to 255 characters
- manage_urlstring or nullOptional
  Link to change or cancel.
otpobject or nullOptional
A one-time password. The code is encrypted at rest until it was sent, then removed; it never appears in logs or in the console.
Show child attributesHide child attributes
- codestringRequired
  The code.
  1 to 64 characters
- expires_in_secondsinteger or nullOptional
  Validity.
- purposestring or nullOptional
  What it is for.
  Up to 120 characters
userobject or nullOptional
A site account.
Show child attributesHide child attributes
- idstring or integer or nullOptional
  User ID.
- loginstring or nullOptional
  Login name.
  Up to 255 characters
- reset_urlstring or nullOptional
  Password reset link. Treated like a one-time password.
commentobject or nullOptional
A comment.
Show child attributesHide child attributes
- idstring or integer or nullOptional
  Comment ID.
- post_titlestring or nullOptional
  Post title.
  Up to 500 characters
- post_urlstring or nullOptional
  Post address.
- excerptstring or nullOptional
  Excerpt.
  Up to 2000 characters
dataobjectOptional
Free-form extras, up to 32 KB, available as {{data.*}}. data.admin_recipients adds recipients to owner automations; data.cart_id on an order cancels the reminder of that cart.

Responses

200
The id was seen before. The first receipt, with status: "duplicate".
202
Received. status is accepted or ignored.
400
Bad request.
parameter_missing parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The key may not push events, or the source is disabled.
scope_missing ip_not_allowed account_suspended source_disabled
404
The source does not exist in this account and mode.
resource_missing
413
The body exceeds 256 KB.
payload_too_large
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/automation_events

Example

curl https://api.omnimessage.co/v1/automation_events \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "woocommerce:order:5012:order.paid:1",
    "type": "order.paid",
    "occurred_at": "2026-10-05T09:30:00Z",
    "site": {
      "name": "Acme Shop",
      "url": "https://shop.example.com/"
    },
    "customer": {
      "id": "17",
      "name": "Layla Hassan",
      "first_name": "Layla",
      "last_name": "Hassan",
      "phone": "+971501234567",
      "email": "layla@example.com",
      "locale": "en",
      "country": "AE",
      "consent": {
        "transactional": true,
        "marketing": true,
        "source": "checkout_checkbox",
        "collected_at": "2026-10-05T09:29:40Z"
      }
    },
    "order": {
      "id": "5012",
      "number": "1042",
      "status": "processing",
      "previous_status": "pending",
      "currency": "AED",
      "total": {
        "amount_minor": 12550,
        "currency": "AED",
        "formatted": "AED 125.50"
      },
      "subtotal": {
        "amount_minor": 8000,
        "currency": "AED",
        "formatted": "AED 80.00"
      },
      "shipping_total": {
        "amount_minor": 1500,
        "currency": "AED",
        "formatted": "AED 15.00"
      },
      "discount_total": {
        "amount_minor": 0,
        "currency": "AED",
        "formatted": "AED 0.00"
      },
      "items": [
        {
          "id": "11",
          "name": "Mug",
          "sku": "MUG-1",
          "quantity": 2,
          "unit_price": {
            "amount_minor": 4000,
            "currency": "AED",
            "formatted": "AED 40.00"
          },
          "url": "https://shop.example.com/mug"
        }
      ],
      "items_count": 2,
      "items_summary": "2 × Mug",
      "payment_method": "cod",
      "payment_method_title": "Cash on delivery",
      "shipping_method": "Flat rate",
      "tracking": {
        "number": "",
        "url": "",
        "carrier": ""
      },
      "status_url": "https://shop.example.com/my-account/view-order/5012/",
      "note": "",
      "created_at": "2026-10-05T09:29:41Z"
    },
    "data": {},
    "source": "src_9Kd2mQ5vB8cX1zL0pK3j"
  }'

Response · 200

{
  "id": "aev_3kL9pQ2wE5rT8yU1iO4a",
  "object": "automation_event",
  "mode": "live",
  "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j",
  "event_id": "woocommerce:order:5012:order.paid:1",
  "type": "order.paid",
  "status": "duplicate",
  "reason": null,
  "automations_matched": 1,
  "received_at": "2026-10-05T09:30:00.120Z"
}

List event receipts#

GET/v1/automation_eventsScopeevents:read

Returns the receipts of the key mode, newest first. For debugging and support; receipts are kept for 30 days.

Query parameters

sourcestringOptional
Only events of this integration source.
typestringOptional
Only events of this type.
statusstringOptional
Only accepted or only ignored events.
Possible valuesacceptedignored
created_aftertimestampOptional
Only events received after this ISO-8601 timestamp.
limitintegerOptional
Number of objects to return, 1 to 100. Default 20.
starting_afterstringOptional
Cursor for the next page: the next_cursor of the previous response (the ID of its last object).

Responses

200
A page of receipts.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/automation_events

curl "https://api.omnimessage.co/v1/automation_events?source=src_9Kd2mQ5vB8cX1zL0pK3j&type=order.paid&created_after=2026-10-01T00%3A00%3A00Z" \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "id": "aev_3kL9pQ2wE5rT8yU1iO4a",
      "object": "automation_event",
      "mode": "live",
      "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j",
      "event_id": "woocommerce:order:5012:order.paid:1",
      "type": "order.paid",
      "status": "accepted",
      "reason": null,
      "automations_matched": 1,
      "received_at": "2026-10-05T09:30:00.120Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Push a batch of events#

POST/v1/automation_events/batchScopeevents:write

Pushes up to 100 events in one request, processed in order (a later event may cancel what an earlier one scheduled). Each item is validated and deduplicated on its own.

The response is 207 Multi-Status whenever the batch itself was well-formed. A batch counts as one request for rate limiting.

Request body

eventsarray of objectsRequired
1 to 100 events, processed in order.
1 to 100 items
Show child attributesHide child attributes
- idstringRequired
  Unique per source for one real-world occurrence: the idempotency key of the event. Build it from stable parts (<platform>:<object>:<object id>:<type>:<sequence>), never from the time of the send attempt.
  1 to 255 characters
- typestringRequired
  One of the documented event types, or custom.<name> with a name of lower-case letters, digits, dots and underscores (up to 64 characters).
- occurred_attimestampRequired
  When it happened at the source. Delays of automations are measured from this instant. Older than 7 days: stored and ignored (stale). More than 10 minutes ahead: 400.
- sourcestringOptional
  The integration source the event belongs to (src_…). Required with an API key, refused with a source key.
- testbooleanOptional
  A test send from a plugin: automations run without delay and quiet hours, and the event is left out of the statistics.
- siteobject or nullOptional
  The store or site. Falls back to the name and URL of the source.
  Show child attributesHide child attributes
  namestring or nullOptional
  Name.
  Up to 255 characters
  urlstring or nullOptional
  Address.
- customerobject or nullOptional
  Optional for events addressed to the account owner only.
  Show child attributesHide child attributes
  idstring or integer or nullOptional
  The platform's customer ID.
  namestring or nullOptional
  Full name. Built from first and last name when omitted.
  Up to 255 characters
  first_namestring or nullOptional
  First name.
  Up to 120 characters
  last_namestring or nullOptional
  Last name.
  Up to 120 characters
  phonestring or nullOptional
  Phone number in E.164 format. A number in another format is normalised like phone_raw.
  Up to 40 characters
  phone_rawstring or nullOptional
  The number as the customer typed it. Read as a national number of country (then of the account's country) when phone is not E.164.
  Up to 60 characters
  emailstring or nullOptional
  Email address.
  Up to 254 characters
  localestring or nullOptional
  BCP 47 language tag. Selects the language variant of the automation.
  Up to 35 characters
  countrystring or nullOptional
  ISO 3166-1 alpha-2 country code.
  Up to 2 characters
  consentobject or nullOptional
  What the customer agreed to, as the source knows it.
  Show child attributesHide child attributes
  transactionalboolean or nullOptional
  true, false, or null for unknown.
  marketingboolean or nullOptional
  true, false, or null for unknown. Marketing automations need true.
  channelsobjectOptional
  Per channel type; wins over the two flags for that channel.
  sourcestring or nullOptional
  Where the consent came from, for example checkout_checkbox.
  Up to 120 characters
  collected_atstring or nullOptional
  When it was collected (ISO-8601).
- orderobject or nullOptional
  Show child attributesHide child attributes
  idstring or integerRequired
  The platform's order ID.
  numberstring or integer or nullOptional
  The order number customers see.
  statusstring or nullOptional
  Current status on the platform.
  Up to 64 characters
  previous_statusstring or nullOptional
  Status before the change.
  Up to 64 characters
  currencystring or nullOptional
  ISO 4217 code.
  Up to 3 characters
  totalobject or nullOptional
  Order total.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
  subtotalobject or nullOptional
  Subtotal.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
  shipping_totalobject or nullOptional
  Shipping.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
  discount_totalobject or nullOptional
  Discounts.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
  itemsarray of objectsOptional
  Line items.
  Show child attributesHide child attributes
  idstring or integer or nullOptional
  Product ID.
  namestring or nullOptional
  Product name.
  Up to 500 characters
  skustring or nullOptional
  SKU.
  Up to 255 characters
  quantitynumber or nullOptional
  Quantity.
  unit_priceobject or nullOptional
  Price of one unit.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
  urlstring or nullOptional
  Product page.
  image_urlstring or nullOptional
  Product image.
  items_countnumber or nullOptional
  Number of units.
  items_summarystring or nullOptional
  Line items as one line of text, for example 2 × Mug.
  Up to 2000 characters
  payment_methodstring or nullOptional
  Payment method code.
  Up to 120 characters
  payment_method_titlestring or nullOptional
  Payment method as the customer sees it.
  Up to 255 characters
  shipping_methodstring or nullOptional
  Shipping method.
  Up to 255 characters
  trackingobject or nullOptional
  Shipment tracking.
  Show child attributesHide child attributes
  numberstring or nullOptional
  Tracking number.
  Up to 255 characters
  urlstring or nullOptional
  Tracking page.
  carrierstring or nullOptional
  Carrier.
  Up to 120 characters
  status_urlstring or nullOptional
  Where the customer can follow the order.
  notestring or nullOptional
  Note to the customer.
  Up to 4000 characters
  created_atstring or nullOptional
  When the order was placed (ISO-8601).
- cartobject or nullOptional
  Show child attributesHide child attributes
  idstring or integerRequired
  Stable ID of the cart or checkout. A later event with the same ID replaces the pending reminder; an order carrying it in data.cart_id cancels it.
  currencystring or nullOptional
  ISO 4217 code.
  Up to 3 characters
  totalobject or nullOptional
  Cart total.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
  itemsarray of objectsOptional
  Line items.
  Show child attributesHide child attributes
  idstring or integer or nullOptional
  Product ID.
  namestring or nullOptional
  Product name.
  Up to 500 characters
  skustring or nullOptional
  SKU.
  Up to 255 characters
  quantitynumber or nullOptional
  Quantity.
  unit_priceobject or nullOptional
  Price of one unit.
  Show child attributesHide child attributes
  amount_minorintegerRequired
  Amount in minor units, using the ISO 4217 exponent of the currency: 0 for JPY, 3 for KWD, BHD, OMR, JOD and TND, otherwise 2.
  currencystringRequired
  ISO 4217 currency code.
  3 to 3 characters
  formattedstringOptional
  The amount as the shop shows it, for example AED 125.50. This is what {{order.total.formatted}} prints.
  Up to 64 characters
  urlstring or nullOptional
  Product page.
  image_urlstring or nullOptional
  Product image.
  items_countnumber or nullOptional
  Number of units.
  items_summarystring or nullOptional
  Line items as one line of text.
  Up to 2000 characters
  recovery_urlstring or nullOptional
  Link that restores the cart.
  updated_atstring or nullOptional
  Last cart activity (ISO-8601).
- formobject or nullOptional
  A form submission.
  Show child attributesHide child attributes
  pluginstring or nullOptional
  Form plugin.
  Up to 120 characters
  idstring or integer or nullOptional
  Form ID.
  namestring or nullOptional
  Form name.
  Up to 255 characters
  fieldsobjectOptional
  Label → value.
  fields_summarystring or nullOptional
  The fields as text, one per line.
  Up to 8000 characters
  page_urlstring or nullOptional
  Page the form is on.
- appointmentobject or nullOptional
  An appointment.
  Show child attributesHide child attributes
  idstring or integerRequired
  Appointment ID.
  servicestring or nullOptional
  Service.
  Up to 255 characters
  starts_atstring or nullOptional
  Start (ISO-8601).
  ends_atstring or nullOptional
  End (ISO-8601).
  timezonestring or nullOptional
  IANA time zone of the appointment.
  Up to 64 characters
  locationstring or nullOptional
  Where.
  Up to 500 characters
  staffstring or nullOptional
  With whom.
  Up to 255 characters
  manage_urlstring or nullOptional
  Link to change or cancel.
- otpobject or nullOptional
  A one-time password. The code is encrypted at rest until it was sent, then removed; it never appears in logs or in the console.
  Show child attributesHide child attributes
  codestringRequired
  The code.
  1 to 64 characters
  expires_in_secondsinteger or nullOptional
  Validity.
  purposestring or nullOptional
  What it is for.
  Up to 120 characters
- userobject or nullOptional
  A site account.
  Show child attributesHide child attributes
  idstring or integer or nullOptional
  User ID.
  loginstring or nullOptional
  Login name.
  Up to 255 characters
  reset_urlstring or nullOptional
  Password reset link. Treated like a one-time password.
- commentobject or nullOptional
  A comment.
  Show child attributesHide child attributes
  idstring or integer or nullOptional
  Comment ID.
  post_titlestring or nullOptional
  Post title.
  Up to 500 characters
  post_urlstring or nullOptional
  Post address.
  excerptstring or nullOptional
  Excerpt.
  Up to 2000 characters
- dataobjectOptional
  Free-form extras, up to 32 KB, available as {{data.*}}. data.admin_recipients adds recipients to owner automations; data.cart_id on an order cancels the reminder of that cart.

Responses

207
Per-item results.
400
The envelope is malformed: events is missing, not an array, empty or longer than 100.
parameter_missing parameter_invalid invalid_json
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The key may not push events, or the source is disabled.
scope_missing ip_not_allowed account_suspended source_disabled
413
The body exceeds 256 KB.
payload_too_large
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/automation_events/batch

curl https://api.omnimessage.co/v1/automation_events/batch \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "id": "woocommerce:order:5012:order.paid:1",
        "type": "order.paid",
        "occurred_at": "2026-10-05T09:30:00Z",
        "site": {
          "name": "Acme Shop",
          "url": "https://shop.example.com/"
        },
        "customer": {
          "id": "17",
          "name": "Layla Hassan",
          "first_name": "Layla",
          "last_name": "Hassan",
          "phone": "+971501234567",
          "email": "layla@example.com",
          "locale": "en",
          "country": "AE",
          "consent": {
            "transactional": true,
            "marketing": true,
            "source": "checkout_checkbox",
            "collected_at": "2026-10-05T09:29:40Z"
          }
        },
        "order": {
          "id": "5012",
          "number": "1042",
          "status": "processing",
          "previous_status": "pending",
          "currency": "AED",
          "total": {
            "amount_minor": 12550,
            "currency": "AED",
            "formatted": "AED 125.50"
          },
          "subtotal": {
            "amount_minor": 8000,
            "currency": "AED",
            "formatted": "AED 80.00"
          },
          "shipping_total": {
            "amount_minor": 1500,
            "currency": "AED",
            "formatted": "AED 15.00"
          },
          "discount_total": {
            "amount_minor": 0,
            "currency": "AED",
            "formatted": "AED 0.00"
          },
          "items": [
            {
              "id": "11",
              "name": "Mug",
              "sku": "MUG-1",
              "quantity": 2,
              "unit_price": {
                "amount_minor": 4000,
                "currency": "AED",
                "formatted": "AED 40.00"
              },
              "url": "https://shop.example.com/mug"
            }
          ],
          "items_count": 2,
          "items_summary": "2 × Mug",
          "payment_method": "cod",
          "payment_method_title": "Cash on delivery",
          "shipping_method": "Flat rate",
          "tracking": {
            "number": "",
            "url": "",
            "carrier": ""
          },
          "status_url": "https://shop.example.com/my-account/view-order/5012/",
          "note": "",
          "created_at": "2026-10-05T09:29:41Z"
        },
        "data": {},
        "source": "src_9Kd2mQ5vB8cX1zL0pK3j"
      },
      {
        "id": "woocommerce:order:5012:order.shipped:1",
        "type": "order.shipped",
        "occurred_at": "2026-10-05T09:30:00Z",
        "site": {
          "name": "Acme Shop",
          "url": "https://shop.example.com/"
        },
        "customer": {
          "id": "17",
          "name": "Layla Hassan",
          "first_name": "Layla",
          "last_name": "Hassan",
          "phone": "+971501234567",
          "email": "layla@example.com",
          "locale": "en",
          "country": "AE",
          "consent": {
            "transactional": true,
            "marketing": true,
            "source": "checkout_checkbox",
            "collected_at": "2026-10-05T09:29:40Z"
          }
        },
        "order": {
          "id": "5012",
          "number": "1042",
          "status": "completed",
          "previous_status": "processing",
          "currency": "AED",
          "total": {
            "amount_minor": 12550,
            "currency": "AED",
            "formatted": "AED 125.50"
          },
          "subtotal": {
            "amount_minor": 8000,
            "currency": "AED",
            "formatted": "AED 80.00"
          },
          "shipping_total": {
            "amount_minor": 1500,
            "currency": "AED",
            "formatted": "AED 15.00"
          },
          "discount_total": {
            "amount_minor": 0,
            "currency": "AED",
            "formatted": "AED 0.00"
          },
          "items": [
            {
              "id": "11",
              "name": "Mug",
              "sku": "MUG-1",
              "quantity": 2,
              "unit_price": {
                "amount_minor": 4000,
                "currency": "AED",
                "formatted": "AED 40.00"
              },
              "url": "https://shop.example.com/mug"
            }
          ],
          "items_count": 2,
          "items_summary": "2 × Mug",
          "payment_method": "cod",
          "payment_method_title": "Cash on delivery",
          "shipping_method": "Flat rate",
          "tracking": {
            "number": "AX204981557",
            "url": "https://track.example.com/AX204981557",
            "carrier": "Aramex"
          },
          "status_url": "https://shop.example.com/my-account/view-order/5012/",
          "note": "",
          "created_at": "2026-10-05T09:29:41Z"
        },
        "data": {},
        "source": "src_9Kd2mQ5vB8cX1zL0pK3j"
      }
    ]
  }'

Response · 207

{
  "object": "batch",
  "data": [
    {
      "index": 0,
      "status": 202,
      "event": {
        "id": "aev_3kL9pQ2wE5rT8yU1iO4a",
        "object": "automation_event",
        "mode": "live",
        "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j",
        "event_id": "woocommerce:order:5012:order.paid:1",
        "type": "order.paid",
        "status": "accepted",
        "reason": null,
        "automations_matched": 1,
        "received_at": "2026-10-05T09:30:00.120Z"
      }
    },
    {
      "index": 1,
      "status": 202,
      "event": {
        "id": "aev_8Jk3mP6qR9sT2vW5xY1z",
        "object": "automation_event",
        "mode": "live",
        "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j",
        "event_id": "woocommerce:order:5012:order.shipped:1",
        "type": "order.shipped",
        "status": "accepted",
        "reason": null,
        "automations_matched": 1,
        "received_at": "2026-10-05T09:30:00.120Z"
      }
    }
  ],
  "accepted": 2,
  "rejected": 0
}

Retrieve an event receipt#

GET/v1/automation_events/{id}Scopeevents:read

Returns one receipt with its runs: what each matched automation did.

Path parameters

idstringRequired
Automation event ID.

Responses

200
The receipt.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/automation_events/{id}

curl https://api.omnimessage.co/v1/automation_events/aev_3kL9pQ2wE5rT8yU1iO4a \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "aev_3kL9pQ2wE5rT8yU1iO4a",
  "object": "automation_event",
  "mode": "live",
  "source_id": "src_9Kd2mQ5vB8cX1zL0pK3j",
  "event_id": "woocommerce:order:5012:order.paid:1",
  "type": "order.paid",
  "status": "accepted",
  "reason": null,
  "automations_matched": 1,
  "received_at": "2026-10-05T09:30:00.120Z",
  "runs": [
    {
      "automation_id": "aut_5Cf8hK1mP4rT7vY0aD3g",
      "status": "sent",
      "scheduled_for": "2026-10-05T09:30:00.120Z",
      "message_id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
      "skip_reason": null
    }
  ]
}

Receive a native platform webhook#

POST/v1/ingest/{platform}/{source_id}Any valid API key

Where a platform can deliver signed webhooks by itself, point them here and no plugin is needed. There is no bearer token: the platform signs the **raw body** with the signing secret of the source, base64(HMAC-SHA256(raw body, secret)), in X-WC-Webhook-Signature (WooCommerce) or X-Shopify-Hmac-Sha256 (Shopify).

The delivery is stored and acknowledged at once; it is normalised into automation events afterwards. A delivery ID that was received before (X-WC-Webhook-Delivery-ID, X-Shopify-Webhook-Id) is acknowledged and not processed again. Topics that are not mapped are acknowledged and ignored, so that the platform never disables the webhook. The unsigned, form-encoded ping WooCommerce sends when a webhook is saved is answered with 200.

Path parameters

platformstringRequired
The platform that sends the webhook.
Possible valueswoocommerceshopify
source_idstringRequired
Integration source ID.

Request body

Responses

200
The signature is valid and the delivery is queued (or was received before).
400
Unknown platform, or a signed body that is not a JSON object.
parameter_invalid invalid_json
401
The signature header is missing or does not match the body.
webhook_signature_invalid
403
The source is disabled.
source_disabled
404
No such integration source.
resource_missing
413
The body exceeds 256 KB.
payload_too_large
429
More than 50 deliveries per second for this source.
rate_limit_exceeded
500
Server error.
internal_error

POST/v1/ingest/{platform}/{source_id}

curl https://api.omnimessage.co/v1/ingest/woocommerce/src_9Kd2mQ5vB8cX1zL0pK3j \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 5012,
    "number": "1042",
    "status": "processing",
    "currency": "AED",
    "total": "125.50",
    "billing": {
      "first_name": "Layla",
      "last_name": "Hassan",
      "phone": "050 123 4567",
      "country": "AE",
      "email": "layla@example.com"
    },
    "line_items": [
      {
        "product_id": 11,
        "name": "Mug",
        "quantity": 2,
        "price": "40.00"
      }
    ],
    "date_modified_gmt": "2026-10-05T09:30:00"
  }'

Response · 200

{
  "received": true
}