Review Requests API

Review requests generate unique hub URLs that you share with customers. Each link takes the customer to a page where they can review their purchased products via AI-guided chat.

Create Review Request

POST /api/v1/review-requests/send

Creates a review request and returns a hub URL.

Request

{
  "email": "customer@example.com",
  "customer_name": "Jane Doe",
  "product_ids": ["shopify-7125386199075", "shopify-7125386199076"],
  "order_id": "ORD-1234",
  "delay_days": 0,
  "skip_email": true
}

Field	Type	Required	Description
email	string	Yes	Customer email (encrypted at rest)
customer_name	string	No	Customer name (encrypted at rest)
product_ids	string[]	No	Shopify product IDs (format: shopify-{id})
order_id	string	No	Order reference (auto-generated if omitted)
delay_days	integer	No	Days before email is sent (default: 7). Use 0 for immediate.
skip_email	boolean	No	If true, no email is sent. You get the hub_url to share manually.

Response (201)

{
  "ok": true,
  "request_id": 456,
  "status": "manual",
  "scheduled_at": "2026-03-27T14:00:00Z",
  "hub_url": "https://api.betterreviews.app/review/hub?token=..."
}

Status values:

• manual — Created with skip_email: true. Share the hub_url yourself.
• scheduled — Email will be sent automatically after delay_days.

Errors

• 422 invalid_email — Email format is invalid
• 409 duplicate_request — Active request already exists for this email + order

---

List Review Requests

GET /api/v1/review-requests

Returns the 50 most recent review requests.

Response (200)

{
  "requests": [
    {
      "id": 456,
      "order_id": "ORD-1234",
      "product_ids": ["shopify-7125386199075"],
      "status": "manual",
      "sent_at": null,
      "inserted_at": "2026-03-27T14:00:00Z"
    }
  ]
}

---

Cancel Review Request

DELETE /api/v1/review-requests/:id

Cancels a review request. The hub URL stops working.

Response (200)

{"ok": true}

---

Hub URL Behavior

• Each hub URL is unique per customer per request
• Valid for 90 days after creation
• Shows all products from the product_ids array
• Customer reviews each product via AI chat or simple form
• Expired links show a "Link Expired" page with option to request a new one