Orders and refunds API overview
Used byCustom website, Shopify, Mobile SDKs
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 | POST /carts |
Report every paid order |
| Report refunds | POST /refunds |
Net refunded money out of an order’s revenue |
| 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.
Authentication
Section titled “Authentication”Send your shop’s secret key as a bearer token:
authorization: Bearer $RELEVA_SECRET_KEYThe 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.
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
Section titled “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 get400 {"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
Section titled “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:
{ "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
Section titled “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
Section titled “Versioning”Both endpoints are under /api/v0. Changes are listed in the API changelog. Unknown fields are rejected, so add new fields only after they appear in the reference.