How orders and refunds work
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
Section titled “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.
An order needs a customer
Section titled “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
Section titled “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
Section titled “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:
- Looks each line item up in your catalog by
idand 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 whoseidmatches nothing still counts towards revenue, but carries no product attributes and shows its product id instead of a name under Details in the admin. - Converts each line to your shop currency (
price × quantity, then the exchange rate forcurrency). A line withoutcurrencyis treated as already in the shop currency. - Stamps the campaign, email, recommender or ad the sale is attributed to on each line.
- 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
Section titled “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 refundedquantity. Omitquantity, 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
valueis 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
Section titled “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
Section titled “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
Section titled “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.