# Product reviews for headless and custom stores

> Connect any online store to Reytd through its API: send products and orders, get review requests after delivery, test in a sandbox, and show the reviews.

Reytd works with any online store that can call an API: a custom-built shop, a headless storefront, or a store run from its own order system. Your store sends its products, orders and shipments; once you've turned review requests on, Reytd asks each customer for a review after delivery, and the reviews show on your product pages, through our widgets or your own code. No plugin required, just an API and a little enthusiasm.

_Figure: Your store sends products, orders and shipments to Reytd's API. After delivery, Reytd emails the customer a review request. The customer leaves a review. The review shows on your product pages._

WooCommerce shops connect with our plugin instead: see [Product reviews for WooCommerce](https://reytd.com/docs/integrations/woocommerce.md). The Shopify app is coming soon; until then, Shopify stores connect the same way, through the API.

## How it works

Every path below starts at `https://reytd.com/api`, so `POST /v1/orders` is `https://reytd.com/api/v1/orders`, and every call sends your token in an `Authorization: Bearer` header. `GET /v1/store` answers with your store for any valid token: a quick way to check one works.

1. **Send your products.** Through the API (`POST /v1/products`, up to 250 at a time) or, on Growth and Pro, as a CSV or Excel import in Reytd. Each product needs your own id (`external_id`) and its name; add its link and image too, so review emails and widgets show the right product.
2. **Send your orders as they come in.** `POST /v1/orders` with the customer's email address and the products they bought, up to 25 orders at a time. A product Reytd doesn't know yet is created from the order, so an order never fails because the product sync is behind. Everything is matched on your own ids and nothing is ever deleted: when an order changes, send its whole current state again.
3. **Send each shipment.** `POST /v1/fulfillments` when an order ships, with `shipped_at` and, when you know it, `delivered_at`.
4. **Send what comes back.** `POST /v1/returns` when a customer returns items, with how many of each: a customer isn't asked to review a product they sent back. Send it when the customer asks to return or when the items arrive, as suits your store; sending it when they ask keeps a review request from going out while the item is on its way back.
5. **Reytd asks for the review**, once you've turned review requests on in Reytd (under **Review requests**; they start switched off, and only orders shipped after that get one). A few days after delivery, as you choose in Reytd, the customer gets an email in their language with the products to review and one-tap stars, and a reminder if they haven't reviewed (unless you turn it off).

Here's an order, and Reytd's answer:

`POST /v1/orders`:

```json
{
  "orders": [
    {
      "external_id": "5001",
      "number": "#1001",
      "placed_at": "2026-10-27T09:30:00+01:00",
      "customer": {
        "email": "anna@example.com",
        "first_name": "Anna",
        "locale": "sv-SE"
      },
      "line_items": [
        {
          "external_id": "1",
          "quantity": 1,
          "product": {
            "external_id": "10001",
            "name": "Everyday Glass Bottle",
            "sku": "EGB-500"
          }
        }
      ]
    }
  ]
}
```

Reytd's answer:

```json
{
  "success": true,
  "data": {
    "summary": {
      "created": 1,
      "updated": 0,
      "products_created": 1,
      "failed": 0,
      "failures": []
    }
  },
  "errors": null,
  "meta": {
    "trace_id": "api@rey:20261027-090000-000:a7fdwk",
    "livemode": false
  }
}
```

Trying it yourself? Change `placed_at` to a recent date first: orders placed more than 30 days ago are turned away.

Every response has the same shape: `success`, `data`, `errors` and `meta`. When you send a batch, every valid item is saved even if others aren't, so a batch answers `200` with `success: true` even when some items failed: check `data.summary.failed`. `data.summary.failures` lists the ones that weren't saved, each with a `code` your integration can act on. See [Sending in batches](https://reytd.com/docs/api.json).

## Build it in the sandbox first

Every store has a sandbox: its own products, orders, reviews and review requests, apart from the live store's. Its emails are simulated, so you can test the whole loop, from an order to a review, without emailing a real customer.

_Figure: A live token, starting rytd\_live\_, reads and writes your store's real data. A sandbox token, starting rytd\_test\_, reads and writes the sandbox, whose emails are simulated and never sent._

- **Create a sandbox token** in Reytd under **Developer › API tokens**: choose **Sandbox**, and what it may do, such as `products:write` and `orders:write` (which covers fulfillments and returns too). Make a **Live** one when you're ready.
- **Both use the same addresses.** The token decides which data a call reads and writes, so going live is changing the token.
- **Check every response's `meta.livemode`:** `true` from live, `false` from the sandbox, and `null` when the token wasn't valid.
- **Try it in Postman** with our [collection](https://reytd.com/docs/postman/reytd-api.postman_collection.json): every endpoint, with example requests.

In the sandbox, use **Send now** (under **Runs**) on a waiting review request to skip its wait, then follow the simulated email's link to leave a review.

## Show the reviews

Choose how the reviews appear on your store:

The widgets, on every plan:

```html
<div class="reytd-stars" data-product="10001"></div>
```

Your own code, on the Enterprise plan (ask us at hello@reytd.com): `GET /v1/reviews?filter[product_external_id]=10001` returns the approved reviews as JSON (`rating`, `title`, `author_name`, …).

- **The widgets.** Add one script tag to your site, then an element where each widget goes, named by the same product id you send through the API. The star rating badge and the reviews widget (every plan) and review carousels (Growth and Pro) draw themselves and pick up your theme's font; in our speed tests, the stars show in less than 50 ms. See [Add review widgets to your store](https://reytd.com/docs/widgets.md).
- **Your own code.** Read the approved reviews with `GET /v1/reviews`, on the Enterprise plan ([ask us](mailto:hello@reytd.com)) with a token that has `reviews:read`, and show them in your own components, for example in a headless frontend.

## Keep in sync

Your store sends what changes (an order's whole current state, each time). To keep your own copy of Reytd's data, such as new reviews, ask only for what's changed since your last sync:

_Figure: Each sync asks for the rows updated since the last one, a minute or two of overlap included, and follows next\_page\_url until has\_next\_page is false._

Each sync reads only what changed. Follow `next_page_url` until `has_next_page` is `false`, up to 100 rows a page.

- Every list takes `filter[updated_since]`, so a sync reads only the rows that changed.
- Lists page by cursor: follow `meta.pagination.next_page_url` until `has_next_page` is `false`, up to 100 rows a page. A row that changes while you page can't push another out of view.
- Save each row by its `id`, and start the next sync a few minutes before the newest `updated_at` you saw. See [Keeping in sync](https://reytd.com/docs/api.json).
- A product's rating changing doesn't change its `updated_at`: to keep a copy of ratings, read all your products again on a schedule, for example once a day.
- Syncing reviews? Ask for `filter[status]=approved,hidden`: a review the store hid comes back with just its `id`, `status` and `updated_at`, so you know to take it down.

## If no review requests go out

Check these, in order:

- **Review requests are switched off.** They're off to start with: add a reply-to address under **Review requests** in Reytd, then turn them on.
- **The order shipped before you turned them on.** Only orders shipped after that get one.
- **The order hasn't shipped in full.** A review request waits until every line item has shipped: send a fulfillment for each. If an item was taken off the order, send the order again with that item's `quantity: 0` (a fulfillment can't have zero).
- **The customer returned everything.** A customer isn't asked to review what they sent back, so an order returned in full gets no review request. Cancelling the return later doesn't start it again.
- **It's still waiting.** It goes out 5 days after delivery by default, or 14 days after shipping if you don't send `delivered_at`, within your store's email hours. The waiting ones are listed under **Review requests** in Reytd.
- **The customer got one recently.** A customer gets at most one review request within the days set in _Days between review requests to a customer_ (under **Review requests**), so a repeat customer's next one waits until then.
- **The customer opted out**, or an earlier email to them bounced or was marked as spam: they aren't emailed again.
- **The month's review requests are used up** (100 a month on Free). New ones wait and get one try when the next month starts; if that month's are used up too, they're dropped. Upgrade, and they go out right away, within your email hours.
- **In the sandbox, emails are simulated,** never sent: read them under **Review requests** with the sandbox on, and use **Send now** (under **Runs**) to skip the wait.

## The request log

Every call your store makes to the API is in Reytd under **Developer › Request log** for 30 days: what it sent, what Reytd answered and how long it took. Filter it by outcome, endpoint or token, or paste a trace id to find one call.

Each answer carries its trace id in `meta.trace_id` and the `X-Trace-Id` header (see [Trace ids](https://reytd.com/docs/api.json)). When something looks wrong, look up the call here first; if you write to us, include the trace id and we'll find the same call.

## Limits

- **Per request:** 250 products, 25 orders, 25 fulfillments or 25 returns, and 4 MB of JSON. An order, fulfillment or return has at most 100 line items.
- **New orders** must have been placed in the last 30 days: older ones would never get a review request. A store takes up to 15,000 new orders in a rolling 30 days; updates to orders Reytd already has don't count towards it.
- **Requests:** 120 a minute per store, and the same again for the sandbox. Past that, you get a `429` with a `Retry-After` header.

Sending products, orders, fulfillments and returns works on every plan, Free included; reading reviews through the API is on Enterprise: [ask us](mailto:hello@reytd.com). Free sends up to 100 review requests a month; see [Pricing](https://reytd.com/pricing).

## Next

- [API reference](https://reytd.com/docs/api.json): every endpoint, its fields and its errors, with code samples.
- [Add review widgets to your store](https://reytd.com/docs/widgets.md): the script and the widgets, step by step.
- [Review widgets and page speed](https://reytd.com/docs/widgets/page-speed.md): how light the widgets are, measured, and how to check for yourself.
- [Start free](https://reytd.com/register) and create your first sandbox token.
