# Orders and refunds API overview

> The order calls, one page each, and the authentication, request format, responses and limits they share.

The orders API reports paid orders, refunds and order statuses for one shop. Each call has its own page:

| Call                                                                                    | Endpoint                                 | What it does                                             |
| --------------------------------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------- |
| [Report paid orders](https://releva.ai/documentation/reference/orders/report-paid-orders/)               | `POST /carts`                            | Report every paid order                                  |
| [Report refunds](https://releva.ai/documentation/reference/orders/report-refunds/)                       | `POST /refunds`                          | Net refunded money out of an order’s revenue             |
| [Send order status updates](https://releva.ai/documentation/reference/orders/send-order-status-updates/) | `POST /events` with `orderStatusChanged` | Tell Releva when an order ships, arrives or is cancelled |

All endpoints are under `https://releva.ai/api/v0`.

**When to use it.** Call `POST /carts` for every paid order unless a Releva connector already does it for your platform. Without it, store revenue, attribution and order-based segments do not work. Call `POST /refunds` if you want Releva’s revenue figures to match your books; otherwise a refunded order keeps counting in full. Send status updates for post-purchase messages and order answers from the Sales Agent. For how these fit together, read [How orders and refunds work](https://releva.ai/documentation/learn/orders/how-orders-and-refunds-work/).

## Authentication

Send your shop’s secret key as a bearer token:

```plaintext
authorization: Bearer $RELEVA_SECRET_KEY
```

The key is a UUID and identifies the shop (domain). There is no shop id in the body. Find the **Secret Key** in the Releva admin under **Settings › Shop & Integration**: see [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).

Authentication failures answer **`400`**, not `401`:

| Problem                        | Message                                                                       |
| ------------------------------ | ----------------------------------------------------------------------------- |
| No `authorization` header      | `Authorization header is missing.`                                            |
| Header is not `Bearer <token>` | ``Authorization header is malformed. It should look like `Bearer <string>`.`` |
| Token is not a UUID            | `Authorization header contains an invalid Bearer token.`                      |
| No shop has this key           | `Domain with the provided secret key cannot be found.`                        |

A shop that has been switched off answers **`402`** with `Domain is disabled. Please reach out to support@releva.ai to enable it.`

## Request format

* HTTPS only. Plain HTTP answers `400 {"message":"We do not support non-HTTPS requests."}`.
* Send JSON with `content-type: application/json`. With any other content type the body is not parsed and you get `400 {"message":"The '' field is required."}`.
* Bodies are limited to **800 KB**. Larger bodies answer `413 {"message":"request entity too large"}`. There is no other limit on the number of carts or refunds per request. Send backfills in batches.
* Objects are validated strictly: any key that is not in the schema is rejected with a message naming it.
* Numbers must be JSON numbers. `"price": "39.90"` is rejected.

## Responses

Every successful call answers **`202 Accepted`** with the body `{}`. Processing is asynchronous. A `202` means the request was valid and queued, not that the order or refund was applied: a repeated `orderId`, a repeated `refundId`, and a refund for an unknown or 30-day-old order are all accepted and then skipped.

Errors have one shape:

```plaintext
{ "message": "The 'carts[0].orderId' field is required." }
```

There is no error code or field property. When several fields fail validation, the messages are joined with a space.

| Status | When                                                                                                     |
| ------ | -------------------------------------------------------------------------------------------------------- |
| `202`  | Accepted and queued                                                                                      |
| `400`  | Authentication failed, validation failed, the body could not be parsed, or no cart carried an identifier |
| `402`  | The shop is disabled                                                                                     |
| `413`  | Body larger than 800 KB                                                                                  |
| `500`  | Unexpected error. The body is `{"message":"An internal error occurred."}`. Retry later.                  |

## Limits

* Body size: 800 KB per request.
* Rate limits: none on these endpoints.
* Processing: orders are held for about 30 seconds before they are recorded. Refunds are processed as soon as a worker picks them up.
* Refund window: 30 days after the order.

## Versioning

Both endpoints are under `/api/v0`. Changes are listed in the [API changelog](https://releva.ai/documentation/changelog/api/). Unknown fields are rejected, so add new fields only after they appear in the reference.

## Next steps

* [Report paid orders](https://releva.ai/documentation/reference/orders/report-paid-orders/): Start with the call every integration needs, with a field table and a working request.
* [How orders and refunds work](https://releva.ai/documentation/learn/orders/how-orders-and-refunds-work/): Learn why one order id is recorded once, what a refund changes and where both show up.
* [See a customer’s orders](https://releva.ai/documentation/guides/orders/see-a-customers-orders/): Check in the admin that the orders you sent appear on the customer’s profile.
* [Catalog API overview](https://releva.ai/documentation/reference/catalog/overview/): Send the products whose ids you use on order line items.