# Report refunds

> POST /api/v0/refunds: take refunded money out of an order's revenue, by line items or by amount, with a working curl, responses, errors and limits.

`POST /api/v0/refunds` nets refunded money out of the revenue of an order you reported with [Report paid orders](https://releva.ai/documentation/reference/orders/report-paid-orders/).

## 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](https://releva.ai/documentation/reference/events/send-custom-events/).

## 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](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/)). The error messages are in [Orders and refunds API: Authentication](https://releva.ai/documentation/reference/orders/overview/#authentication).

## 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:

```plaintext
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:

```plaintext
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.

### 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

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

`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](https://releva.ai/documentation/reference/orders/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](https://releva.ai/documentation/reference/orders/send-order-status-updates/), 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](https://releva.ai/documentation/guides/orders/check-that-a-refund-was-recorded/).

## Errors

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

| Status | When                          | Message                                                                                                |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------ |
| `400`  | Authentication failed         | See [Orders and refunds API: Authentication](https://releva.ai/documentation/reference/orders/overview/#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

* Body size: 800 KB per request.
* Rate limits: none.
* Refund window: 30 days after the order.

## Next steps

* [How orders and refunds work](https://releva.ai/documentation/learn/orders/how-orders-and-refunds-work/): Learn what a refund changes and where it shows up.
* [Check that a refund was recorded](https://releva.ai/documentation/guides/orders/check-that-a-refund-was-recorded/): Confirm in the admin that the refund was netted out of the order.
* [Send order status updates](https://releva.ai/documentation/reference/orders/send-order-status-updates/): Tell customers and the Sales Agent where an order is.