API reference

Connect your store to Reytd: send your products and orders, and read them back.

The Reytd API lets your store send its products and orders to Reytd and read them back, so customers are asked to review the right products once their order has shipped.

Building your integration with an AI assistant? Connect it to our MCP server, or point it at llms.txt, which lists the docs as Markdown, this reference included.

Authentication

Create an API token in Reytd under Developer › API tokens, and choose what it may do, its abilities: products:read (Read products), products:write (Create and update products), orders:read (Read orders), orders:write (Send orders, fulfillments and returns) and reviews:read (Read reviews). You'll see Developer if you may manage the store's integrations.

Every path in this reference starts at https://reytd.com/api, so GET /v1/store is https://reytd.com/api/v1/store. Send your token as a Bearer token with every request:

Authorization: Bearer YOUR_API_TOKEN

A token belongs to one store and only sees that store's data. A token without the ability an endpoint needs gets 403 token_missing_ability.

To check a token, call GET /v1/store, which any valid token may call. It returns the token's store and its organization, the token's abilities, the widget script for your site, and a link to the store in Reytd.

Live and sandbox

Every store has a sandbox for building and testing an integration: its own products, orders, reviews and review requests, separate from the store's real ones. Review requests are made as in live, but their emails are only built and shown in the sandbox, never sent. In Reytd, switch to the sandbox to:

  • read the emails under Review requests;
  • follow an email's link to leave a test review (it stays in the sandbox, and shows in Reytd's Reviews page in the sandbox);
  • use Send now on a waiting review request, rather than waiting days for it.

When you create a token, choose Live or Sandbox. Both use the same URLs: the token decides which data a call reads and writes, so to move an integration from testing to live, change its token. You can tell them apart by their prefix:

  • rytd_live_... for live tokens;
  • rytd_test_... for sandbox tokens.

Every response says which environment answered in meta.livemode: true for a live token, false for a sandbox token. It's null when the call had no valid token, and on errors returned before the token is read: an unknown endpoint (404), a wrong method (405) and a body that's too large (413). Check it if your integration must never write test data to live, or live data to the sandbox.

Postman

Try the API in Postman with our collection: every endpoint, with example requests.

  1. Import the collection into Postman.
  2. Open the collection's Authorization tab and paste a token: a sandbox token (rytd_test_...) to work with the sandbox, or a live token (rytd_live_...) for your store's real data.
  3. Set the collection's livemode variable to match: false for the sandbox (the default) or true for live.
  4. Send a request.

Try the example orders and fulfillments with a sandbox token first: with a live token they're saved with your store's real data, and can start real review requests.

As in the API itself, the token decides which environment a call uses; the livemode variable doesn't. The collection's tests compare each response's meta.livemode with livemode and fail when they differ, for example with a live token while you expect the sandbox. They run after the request, so they warn you, but can't stop a request going to live.

Responses

Every response has the same four keys, for successes and errors alike:

Key On success On error
success true false
data an object, keyed by what it holds null
errors null { code, message, fields }
meta trace_id, livemode, plus pagination on lists trace_id, livemode

The HTTP status always matches: 2xx with success: true, 4xx or 5xx with success: false. New keys may be added to data over time; existing keys keep their meaning.

Errors

errors.code is stable and safe to check in your code. errors.message is readable text whose wording may improve, so don't match on it. errors.fields lists validation messages per field, and is {} when the error isn't about fields.

  • invalid_query (400): An unsupported filter or sort; the message lists the allowed ones.
  • invalid_json (400): The body isn't valid JSON, was sent without Content-Type: application/json, or holds a NUL character (\u0000), which Reytd can't store in text.
  • unauthenticated (401): No token, or an invalid or revoked one.
  • token_missing_ability (403): The token lacks the ability this action needs.
  • plan_missing_feature (403): The store's plan doesn't include this feature, such as the reviews API (Enterprise: ask us at [email protected]); the message names the plan that has it.
  • forbidden (403): Not allowed for another reason.
  • not_found (404): The resource or endpoint doesn't exist, or isn't in your store.
  • method_not_allowed (405): The endpoint exists, but not for this HTTP method.
  • payload_too_large (413): The body is larger than 4 MB; send fewer items per request.
  • validation_failed (422): Input didn't pass validation; see fields.
  • too_many_requests (429): Rate limit reached; see the Retry-After header.
  • request_failed (4xx): Any other client error; the status code tells which.
  • server_error (500): Something went wrong on our side.
  • service_unavailable (503): Maintenance; try again shortly.

Lists and paging

Lists return one page at a time, per_page items (default 50, at most 100), with the details in meta.pagination. To get the next page, call meta.pagination.next_page_url, and keep going until has_next_page is false (next_page_url is then null).

The link carries a cursor, also in next_cursor, that marks where the page ended, so rows that change while you page through never make you miss one. Lists don't take page numbers, and have no total count.

Filter with filter[field]=value, and sort with sort=field, or sort=-field for descending. Rows with the same sort value are ordered by id. The paging links keep your filters and sorting; use a cursor only with the list, filters and sorting it came from.

These get 422 validation_failed, naming the parameter in fields:

  • a per_page outside 1–100;
  • a page number;
  • a cursor that doesn't fit the list's sorting;
  • a value the filter doesn't take, such as filter[rating]=abc or an unknown status.

Sending in batches

Products, orders, fulfillments and returns are sent in batches, as JSON with Content-Type: application/json. Dates are ISO 8601 text, such as 2026-10-09T12:00:00+02:00, from the year 2000 to 2099; leave a date out (or send null) rather than sending a placeholder such as 0001-01-01. Ids are compared as text, so "12" and "0012" are two ids.

Send your products with POST /v1/products, not only inside orders: customers aren't asked to review a product Reytd knows only from an order's line item. When none of an order's products has been sent yet, its review request waits for them.

Every valid item in a batch is saved, even when others aren't, so the response is 200 with success: true even if every item failed. Check data.summary.failed: data.summary.failures lists each item that wasn't saved, by its index in the request, with a code for your code to act on and a message that explains it.

code What it means
invalid A field isn't valid: fix the one the message names, then send the item again.
order_too_old A new order placed more than 30 days ago; Reytd doesn't take it.
placed_at_ahead A new order placed more than 24 hours ahead; send the time it was placed.
order_limit_reached The store has reached its limit of new orders for 30 days; send it again from the failure's retry_after.
order_not_found A fulfillment's or return's order isn't in Reytd: send the order, then the fulfillment or return again.
line_item_not_found A fulfillment's or return's line item isn't in its order.
over_shipped A fulfillment would ship more of a line item than was ordered.
fulfillment_moved A fulfillment was sent with another order than the one it was saved with.
over_returned A return would bring back more of a line item than was ordered.
return_moved A return was sent with another order than the one it was saved with.
group_full The product's group is full: a group holds at most 50 products.

Products sent with a group_id on a plan without product groups are saved, with a note in data.summary.warnings: the group is kept, and each product shows only its own reviews until the plan includes groups.

One request holds at most:

  • 250 products;
  • 25 orders, each with at most 100 line items;
  • 25 fulfillments, each with at most 100 line items;
  • 25 returns, each with at most 100 line items;
  • 4 MB of JSON.

A request with more items than that, or none, gets 422 validation_failed and saves nothing; a body over 4 MB gets 413 payload_too_large. An order, fulfillment or return with too many line items fails on its own, as invalid.

New orders must have been placed in the last 30 days (or up to 24 hours ahead, for time zones). Older orders would never get a review request, so send orders as they come in; when you connect, the last 30 days are worth sending, but not older history.

Reytd takes up to 15,000 new orders per store in any 30 days. That leaves room for the orders you send when you connect, and for busy sale days. Past that, new orders are listed in failures as order_limit_reached, with the time there's room again in retry_after. Email [email protected] if your store needs more.

Neither limit applies to orders Reytd already has: you can always update them, and send their fulfillments and returns.

Leaving something out of a later request never deletes it: a line item missing from an order is kept as it was.

  • When a line item is removed from an order (an order edit, an item out of stock), send it with quantity: 0. It then doesn't have to ship for the order to count as fulfilled, and the customer isn't asked to review it.
  • When items shipped and came back, send a return (POST /v1/returns) instead. The order keeps what was bought and shipped, and the customer isn't asked to review what they sent back.

Keeping in sync

To keep your copy of the store's products, orders, fulfillments, returns or reviews up to date, ask only for what changed since your last sync:

  1. List with sort=updated_at and filter[updated_since] (leave the filter out the first time), and follow next_page_url until has_next_page is false.
  2. Save each row by its id, replacing the copy you have, and keep the newest updated_at.
  3. Next time, set filter[updated_since] to that time minus 5 minutes. A change saved while your last sync ran can carry a slightly earlier time than rows you've already seen; the overlap catches it, and since you save by id, rows that come twice do no harm.

What counts as a change:

  • Orders change each time you send them, even unchanged, and when the store erases the customer's data (the order's customer details become null). A new or updated fulfillment or return also changes its order's updated_at, so orders synced this way include their latest fulfillments and returns.
  • Products change each time you send them, even unchanged; when Reytd has new image_copies of their image; and when their group is renamed. A product's rating follows its reviews without changing its updated_at: sync reviews for that. The product shown inside an order or a review is as it is now; sync products for changes to it.
  • Reviews change when the store replies to them, hides or shows them, and when it erases the customer's data. Erasing sets author_name to null, and where the title, the text or the reply names the customer (their full name, or their surname after a title or an initial, such as "Mrs Svensson"), the name is replaced with a marker such as "[name removed]", in the language of the text.
  • Hidden reviews are the ones the store has taken down. Add filter[status]=approved,hidden and remove those that come back hidden from your copy; they come with only id, status and updated_at. Reviews waiting for approval are never listed.
  • Groups need care: a product joining or leaving a group doesn't change its reviews' updated_at, so a sync filtered by group_external_id misses the reviews of a product that joins. Sync reviews without that filter and match them to groups through the products you sync, each of which names its group. Or fetch all of a group's reviews when its products change.

Rate limits

Each store can make 120 requests per minute with its live tokens, and another 120 with its sandbox tokens, so testing never uses up your live integration's limit. Past that, requests get 429 too_many_requests, with a Retry-After header saying how many seconds to wait.

Calls with a missing or wrong token count separately, per IP address: after 30 in a minute, that address's calls without a valid token get 429 instead of 401 until the minute is over. Calls with a valid token are never held up by them.

Trace ids

Every response carries a trace id in meta.trace_id and in the X-Trace-Id header, such as api@rey:20261010-215846-941:k3m9x2. Include it when you contact support, so we can find the exact request.