Skip to content

Area: Developers

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.

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

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.

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.

  • 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.

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.
  • 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.

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.

  • Store dataReport paid orders

    Start with the call every integration needs, with a field table and a working request.

  • Store dataHow orders and refunds work

    Learn why one order id is recorded once, what a refund changes and where both show up.

  • Data PlatformSee a customer's orders

    Check in the admin that the orders you sent appear on the customer’s profile.

  • API referenceCatalog API overview

    Send the products whose ids you use on order line items.