# How orders and refunds work

> How a paid order gets into Releva, why one order id is recorded once, what a refund changes, and where orders and refunds show up in the admin.

Orders are what Releva’s revenue, attribution and order-based segments are built on. Refunds correct those numbers. This page explains what happens between the request and the admin screen, so that you know what to send and what to expect.

## Three ways in

| Method                                      | Who drives it                                                                                                               | Best for                                                                                              |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Platform connector** (Shopify and others) | Releva. The connector reports each paid order as it happens; the Shopify connector also reports refunds.                    | Shops on a supported platform. No code.                                                               |
| **Orders API**                              | You call `POST /api/v0/carts` from your backend when an order is paid, and `POST /api/v0/refunds` when money is given back. | Custom shops, ERPs and backfills.                                                                     |
| **JavaScript SDK**                          | The shopper’s browser sends the checkout event.                                                                             | Browsing carts and real-time checkout tracking. A backend order with the same `orderId` wins over it. |

Everything lands in the same place: one **Cart Checkout Completed** event per order and one **Refund** event per refund, on the customer’s profile. There is no orders screen in the admin. See [See a customer’s orders](https://releva.ai/documentation/guides/orders/see-a-customers-orders/).

## An order needs a customer

Every cart must carry at least one of `email`, `phoneNumber` or `profileId`. That is how Releva attaches the order to a profile. Send all you have; they are resolved to one profile.

* A cart with none of the three is dropped. The other carts in the same request are still processed.
* If no cart in the request carries an identifier, the whole request is rejected with `400`.
* On a guest checkout, pass the anonymous browsing id in `mergeProfileIds`, so the pre-purchase browsing history and campaign attribution follow the shopper onto the identified profile.
* An order with a phone number as the only identifier: Releva normalises the number with your shop country’s dialling code before validation. Send `+` followed by digits to avoid surprises.

## One order id, one record

An `orderId` is recorded once per shop. A webhook redelivery, a retry after a timeout or a backfill that overlaps live traffic cannot double-count revenue: the first arrival wins, later ones are accepted with `202` and dropped. Only cart-level `custom` fields of a repeated order are merged onto the stored order.

The flip side: you cannot correct an order by re-sending it. Use a refund to take money back out, or contact support.

Use the order number your own systems use. It is what refunds, support and order-level reports match on.

## Orders are held for 30 seconds

`POST /carts` answers `202` as soon as the request is validated. The order is then held for about 30 seconds so that a browser checkout event for the same order can arrive and be merged, and recorded after that. In the admin, an order appears 30 to 40 seconds after the call.

During processing Releva:

1. Looks each line item up in your catalog by `id` and copies the product’s name, categories and custom fields onto the order. That is what makes segments such as “bought in category X” work. A line whose `id` matches nothing still counts towards revenue, but carries no product attributes and shows its product id instead of a name under **Details** in the admin.
2. Converts each line to your shop currency (`price × quantity`, then the exchange rate for `currency`). A line without `currency` is treated as already in the shop currency.
3. Stamps the campaign, email, recommender or ad the sale is attributed to on each line.
4. Writes the event, keeps a priced copy of the order for 30 days (for refunds), clears the shopper’s browsing cart, and sends a Purchase event to the ad platforms connected to your shop.

A cart sent with `cartPaid: false` still updates the profile, but records no order, no revenue and no event. Use the SDK for carts that have not been paid for.

## What a refund changes

`POST /refunds` nets refunded money back out of the revenue Releva reports. You send only what was refunded and against which `orderId`. The customer, date, prices, currency and attribution come from the stored order, so sending any of them is rejected.

* **Line items** (`products`): each refunded line is matched to the original order and its value subtracted in proportion to the refunded `quantity`. Omit `quantity`, or send 0, to refund the whole line. More than ordered is capped at the line. A line that matches nothing is skipped. Every line keeps its attribution, so the refund comes off the campaign that earned it.
* **Amount only** (`value`): the amount is spread across the order’s lines in proportion to their value, capped at the order’s product total.
* With both, the line items win and `value` is ignored. A partial refund with line items therefore nets only the goods, never shipping or tax, which were not revenue in the first place.

The refund is recorded as a **Refund** event with negative amounts, **dated on the original order’s timestamp**, not today’s. Reports you have already looked at can change after a refund. Loyalty points the order earned are reversed in proportion to the refunded value.

A refund does not start a workflow. To react to a refund, send a custom event as well.

## Refunds are only possible for 30 days

The priced copy of an order is kept for 30 days. A refund for an older order, or for an order Releva never received, is accepted with `202` and skipped. A `refundId` is processed at most once, so retries are safe; one order may have many refunds, each with its own id.

## Where the numbers show up

| Place                                       | What you see                                                                                               | Refunds                                                 |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Profile › **Recent Events**                 | One **Cart Checkout Completed** row per order and one **Refund** row per refund, with **Raw Data**         | Shown as separate rows                                  |
| Profile › **Aggregated Statistics**         | **Orders**, **Customer Value**, **Average Order Value**, **Average Order Size** for the last 1 or 3 months | **Not subtracted**: the tab counts purchase events only |
| **Data Platform › Events**                  | The same events across all customers                                                                       | Shown as separate rows                                  |
| **Analytics**                               | Store, campaign and channel revenue                                                                        | Netted on the order’s date                              |
| **Customer insights** (Lifetime value, RFM) | Model predictions                                                                                          | Computed by a separate job, not right after an order    |

## Order status is a different event

Where an order is after payment (shipped, delivered, cancelled) is sent as an `orderStatusChanged` event with `POST /api/v0/events`, not with the orders API. It shows up as an **Order Status Changed** event on the profile. A status never changes revenue, except a cancellation: about 2 minutes after a `cancelled` status, Releva takes the order back out of revenue, unless the order already has a refund. A refund for an order that was already cancelled is skipped. See [Send order status updates](https://releva.ai/documentation/reference/orders/send-order-status-updates/).

## Next steps

* [Orders and refunds API overview](https://releva.ai/documentation/reference/orders/overview/): Report paid orders and refunds, with auth, limits, errors and a working request for each endpoint.
* [See a customer’s orders](https://releva.ai/documentation/guides/orders/see-a-customers-orders/): Open a profile and see every order Releva recorded for that customer.
* [Check that a refund was recorded](https://releva.ai/documentation/guides/orders/check-that-a-refund-was-recorded/): Confirm that a refund you sent was applied to the order.
* [How your catalog gets into Releva](https://releva.ai/documentation/learn/catalog/how-your-catalog-gets-into-releva/): Learn how the products in your orders reach Releva and how they are identified.