# Send order status updates

> The orderStatusChanged event on POST /api/v0/events: tell Releva where an order is after payment, with the status fields, which platforms send it, how cancellations and Sales Agent answers use it, a working curl and errors.

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

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](https://releva.ai/documentation/reference/orders/report-paid-orders/). To take money back out of your reporting, use [Report refunds](https://releva.ai/documentation/reference/orders/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](https://releva.ai/documentation/reference/orders/send-order-status-updates/#cancellations).

### 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

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](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/)). The error messages are in [Events API: Authentication](https://releva.ai/documentation/reference/events/overview/#authentication).

## Request

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

```plaintext
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](https://releva.ai/documentation/reference/events/send-custom-events/) is accepted too.

### 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

* **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.

### Cancellations

> **A cancelled status changes revenue**
>
> Unlike other statuses, a cancellation takes the order out of revenue. Keep using [Report refunds](https://releva.ai/documentation/reference/orders/report-refunds/) for money you return; a refund for an order that is already cancelled is skipped, so the order leaves revenue once.

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

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.

## Response

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

## Errors

The errors of [Send custom events](https://releva.ai/documentation/reference/events/send-custom-events/#errors) apply. The most common:

| Status | When                                 | Message                                                                                                                                                                                                                                    |
| ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Authentication failed                | See [Events API: Authentication](https://releva.ai/documentation/reference/events/overview/#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

* Body size: 800 KB per request.
* Rate limits: none.
* The Sales Agent reads statuses of the last 30 days only.

## Next steps

* [Report paid orders](https://releva.ai/documentation/reference/orders/report-paid-orders/): Send the paid order first; status updates refer to its `orderId`.
* [How the Sales Agent works](https://releva.ai/documentation/learn/sales-agent/how-the-sales-agent-works/): Learn what the agent can answer and where it appears.
* [Report refunds](https://releva.ai/documentation/reference/orders/report-refunds/): Take refunded money out of revenue alongside a refunded status.