Skip to content

Area: Developers

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.

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.

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.

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.

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.

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.

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.

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

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.