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.
When to use it
Section titled “When to use it”Send them only if you want post-purchase communication or order status answers in chat:
- Post-purchase messages. An
orderStatusChangedevent 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 intags. - 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.
Which platforms send it
Section titled “Which platforms send it”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.
Authentication
Section titled “Authentication”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.
Request
Section titled “Request”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.
The status details
Section titled “The status details”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.
How the statuses are used
Section titled “How the statuses are used”- Current status. Releva keeps every status event. The one with the latest
timestampfor 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
orderIdororderName; a bare number also matches a prefixed name, so1234findsEN1234. It looks at orders from the last 30 days, at most the 10 most recent, and up to 10 items per order.
Cancellations
Section titled “Cancellations”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:
- Your shop runs on Shopify, Magento 1, Magento 2, WooCommerce or a custom integration.
- 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.
Response
Section titled “Response”202 Accepted with the body {}. Events without any identifier are skipped when another event in the request is valid.
Errors
Section titled “Errors”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 |
Limits
Section titled “Limits”- Body size: 800 KB per request.
- Rate limits: none.
- The Sales Agent reads statuses of the last 30 days only.