Report refunds
POST /api/v0/refunds nets refunded money out of the revenue of an order you reported with Report paid orders.
When to use it
Section titled “When to use it”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.
Authentication
Section titled “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). The error messages are in Orders and refunds API: Authentication.
Request
Section titled “Request”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
productsorvaluein one refund, not both. If you send both, the line items are used andvalueis 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 outquantity(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.
Refunds are only possible for 30 days
Section titled “Refunds are only possible for 30 days”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.
Loyalty points
Section titled “Loyalty points”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.
Response
Section titled “Response”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
refundIdthat 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
productsthat match the order nor avalueabove 0. The API does not reject a refund that has neither field.
To check a refund, see Check that a refund was recorded.
Errors
Section titled “Errors”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. |
Limits
Section titled “Limits”- Body size: 800 KB per request.
- Rate limits: none.
- Refund window: 30 days after the order.