Skip to content

Area: Developers

Send order status updates

Order status updates tell Releva where an order is after it has been paid: confirmed, shipped, out for delivery, delivered, cancelled, refunded. They are custom events with the reserved action orderStatusChanged, sent to POST /api/v0/events.

Send them only if you want post-purchase communication or order status answers in chat:

  • Post-purchase messages. An orderStatusChanged event can start a workflow: a “your order has shipped” email, a delivery notification, a review request a few days after delivery. Branch on the value in tags.
  • Order status answers from the Sales Agent. When a customer asks where their order is, the agent answers with the latest status, the items and the tracking link.

Revenue, attribution and order-based segments come from Report paid orders. To take money back out of your reporting, use Report refunds, and when an order is refunded, send both the refund and the status update. A cancelled status has a side effect on revenue: read Cancellations.

The Releva integrations for Shopify, Magento 1, Magento 2 and WooCommerce (plugin 1.0.84 and later) send these events for you; there is nothing to build. On any other platform, or for statuses that live in your ERP rather than your shop, send them yourself as described here.

Send your shop’s Secret Key as a bearer token: authorization: Bearer $RELEVA_SECRET_KEY. Never use it in a browser or an app. Find it under Settings › Shop & Integration (Find your Access Token and Secret Key). The error messages are in Events API: Authentication.

POST https://releva.ai/api/v0/events with content-type: application/json. Send one event each time an order’s status changes.

curl -X POST 'https://releva.ai/api/v0/events' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json' \
-d '{
"events": [
{
"action": "orderStatusChanged",
"orderId": "DEMO-ORDER-1001",
"email": "maria@example.com",
"timestamp": "2026-11-11T10:15:30.000Z",
"tags": ["shipped"],
"custom": {
"string": [
{ "key": "state", "values": ["shipped"] },
{ "key": "statusLabel", "values": ["On its way to you"] },
{ "key": "orderName", "values": ["#1001"] },
{ "key": "trackingNumber", "values": ["DEMO-TRACK-1001"] },
{ "key": "trackingCompany", "values": ["Demo Courier"] },
{ "key": "trackingUrl", "values": ["https://demo-store.example.com/track/DEMO-TRACK-1001"] }
]
},
"products": [
{ "id": "DEMO-1001", "variantId": "DEMO-1001-M", "quantity": 1 }
]
}
]
}'
Field Type Required Notes
action string yes Always orderStatusChanged.
orderId string send it The order, exactly as sent to POST /carts. The endpoint accepts an event without it, but such a status belongs to no order.
email, phoneNumber, profileId string at least one Use the same identifiers as on the order, so the status lands on the same profile.
timestamp string no When the status changed. ISO-8601 with seconds and a zone. Default: now.
tags array of strings yes, in practice The status as one entry: ["shipped"], ["delivered"], ["cancelled"].
custom object no The status details below.
products array of objects no The order’s lines: id, and optionally variantId and quantity. Use the same ids as on the order.

Every other field of Send custom events is accepted too.

Put what a customer may be told about the order in custom.string. These keys are the ones Releva reads:

Key Notes
state The status code, the same as in tags: confirmed, shipped, in_transit, out_for_delivery, delivered, cancelled, refunded, or your platform’s own codes.
statusLabel What the customer should be told, in their language: “On its way to you”, “Ready for pickup”. Send it when your status codes are internal words a customer would not understand, such as an ERP code like zeron_completed. When it is present, this is what the customer sees, and the raw code is never shown. Trimmed to 100 characters.
orderName The order number as the customer knows it (#1001, EN1234), when it differs from orderId. Customers type it when asked for their order number. Send it on the paid order too.
trackingNumber The carrier’s tracking number.
trackingCompany The carrier’s name.
trackingUrl The tracking page the customer can open.

Any other custom field is stored on the event and can be used in segments and workflows, but the Sales Agent never shows it to a customer. That is on purpose: a field such as a cancellation reason can hold information a customer should not read.

  • Current status. Releva keeps every status event. The one with the latest timestamp for an order is its current status, so a late delivery of an older status does not overwrite a newer one, as long as each event carries the time of the change it describes.
  • Sales Agent. The agent finds an order by orderId or orderName; a bare number also matches a prefixed name, so 1234 finds EN1234. It looks at orders from the last 30 days, at most the 10 most recent, and up to 10 items per order.

When state or the first entry of tags is cancelled or canceled (any case), and the event has an orderId, Releva cancels the order about 2 minutes later:

  • It records an order cancellation on the original order’s date that takes the order’s revenue back out, and reverses the loyalty points the order earned.
  • It skips the cancellation when the order already has a refund, or when it was already cancelled.
  • If, by then, the order’s latest status is no longer a cancellation, or the paid order has not arrived yet, it checks again every 5 minutes, up to 5 times, and then gives up.

Turn on order status answers in the Sales Agent

Section titled “Turn on order status answers in the Sales Agent”

The Sales Agent answers order questions only when both are true:

  1. Your shop runs on Shopify, Magento 1, Magento 2, WooCommerce or a custom integration.
  2. Order status answers are switched on for your Sales Agent. Only Releva can switch them on or off: ask your Releva contact. When they are off, the agent declines to answer order questions rather than guess, and sends them to support.

A custom integration must send these events for the agent to know any status.

202 Accepted with the body {}. Events without any identifier are skipped when another event in the request is valid.

The errors of Send custom events apply. The most common:

Status When Message
400 Authentication failed See Events API: Authentication
400 No identifier in any event events[0]: at least one of ('profileId', 'email' or 'phoneNumber') is required!
400 timestamp without a time or zone events[0].timestamp must be a valid ISO-8601 date including seconds and timezone offset with optional milliseconds such as 2020-01-01T23:59:59.999Z or 2020-01-01T23:59:59.999-0500 or 2020-01-01T23:59:59-0500. Got 2026-11-11 instead.
400 A number in custom.string[].values The 'events[0].custom.string[0].values[0]' field must be a string.
402 Your shop is disabled Domain is disabled. Please reach out to support@releva.ai to enable it.
413 Body larger than 800 KB request entity too large
  • Body size: 800 KB per request.
  • Rate limits: none.
  • The Sales Agent reads statuses of the last 30 days only.