Skip to content

Area: Developers

Report refunds

POST /api/v0/refunds nets refunded money out of the revenue of an order you reported with Report paid orders.

Call it if you want Releva’s revenue figures to match your books. Without it, a refunded order keeps counting in full towards store revenue, campaign revenue and channel attribution, so the email, ad or product block that drove the sale looks better than it was.

It only corrects the numbers: it does not start a workflow. To react to a refund with a message, also send a custom event with Send custom events.

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 Orders and refunds API: Authentication.

POST https://releva.ai/api/v0/refunds with content-type: application/json and a body { "refunds": [ ... ] } that holds at least one refund. No other field is accepted: the customer, date, prices and currency come from the stored order.

Field Type Required Notes
orderId string yes The order, as sent to POST /carts.
refundId string yes Your unique id for this refund. Each refundId is processed once.
products array of objects no, but send one of the two The refunded lines: id (required), variantId, quantity. Send variantId whenever you have it: it is what tells two lines of the same product apart.
value number no, but send one of the two An amount, in the order’s currency: shipping, a goodwill credit, a discount after the fact.

Refund line items:

curl -X POST 'https://releva.ai/api/v0/refunds' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json' \
-d '{
"refunds": [
{
"orderId": "DEMO-ORDER-1001",
"refundId": "DEMO-REFUND-1001",
"products": [ { "id": "DEMO-1001", "variantId": "DEMO-1001-M", "quantity": 1 } ]
}
]
}'

Refund an amount:

curl -X POST 'https://releva.ai/api/v0/refunds' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json' \
-d '{ "refunds": [ { "orderId": "DEMO-ORDER-1001", "refundId": "DEMO-REFUND-1002", "value": 12.5 } ] }'

How a refund is applied:

  • Send either products or value in one refund, not both. If you send both, the line items are used and value is ignored.
  • With products, each refunded line is matched against the original order and its value subtracted in proportion to the refunded quantity. Every line keeps the attribution it had on the order, so the refund is subtracted from the same campaign, email or recommender that earned it. Leave out quantity (or send 0) to refund the whole line. More than ordered is capped at the ordered quantity. A line that matches nothing in the order is skipped.
  • Line items net only the goods. Shipping and tax were never counted as revenue on the original order, so a line-item refund does not subtract them. Send an amount-only refund if you want the full amount netted.
  • With value, the amount is spread over the order’s lines in proportion to their value and capped at the order’s product total.
  • The refund is recorded on the original order’s date, not today’s, with negative amounts, so the correction lands in the period the sale was counted in. A report you have already looked at can therefore change after a refund arrives: that is the point.

Releva keeps the priced, attributed copy of an order for 30 days after the sale, and that copy is what a refund is netted against. A refund for an order older than that is accepted with a 202 and then skipped: there is nothing left to subtract it from.

If the order earned loyalty points, they are reversed along with the money. How much comes back depends on the rule that granted them: points granted in proportion to order value are reversed in proportion to the refunded value, while a rule configured to reverse in full does so on any refund of its order. Points from a grant marked as non-reversible, and points that have already expired, are left alone.

202 Accepted with the body {}. Refunds are reflected in reporting within about a minute. A 202 means the request was valid and queued, not that the refund was applied. These are accepted and then skipped:

  • a refundId that was already processed;
  • a refund for an order older than 30 days, or for an order Releva never received. Send your orders with Report paid orders first, or the refunds have nothing to correct;
  • a refund for an order that was already cancelled with an order status update, so the order is not taken out of revenue twice;
  • a refund with neither products that match the order nor a value above 0. The API does not reject a refund that has neither field.

To check a refund, see Check that a refund was recorded.

Errors have one shape, { "message": "..." }.

Status When Message
400 Authentication failed See Orders and refunds API: Authentication
400 Empty refunds The 'refunds' field must contain at least 1 items.
400 Missing refundId The 'refunds[0].refundId' field is required.
400 email on a refund The object 'refunds[0]' contains forbidden keys: 'email'.
400 price on a refunded product The object 'refunds[0].products[0]' contains forbidden keys: 'price'.
400 value: "12.50" (a string) The 'refunds[0].value' field must be a number.
400 quantity: "1" (a string) The 'refunds[0].products[0].quantity' field must be a number.
400 Product without id The 'refunds[0].products[0].id' field is required.
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
500 Unexpected error; retry later An internal error occurred.
  • Body size: 800 KB per request.
  • Rate limits: none.
  • Refund window: 30 days after the order.