Pro
API for invites, reviews & widgets
HTTPS API for invites, reviews, products, and widgets. Paid plan key required. All examples use the public domain ranqa.me.
Base URL: https://ranqa.me
Authentication
Create a key under Dashboard → API. Send it as a Bearer token. Keys start with rnq_ and are scoped to one company.
Authorization: Bearer rnq_…
The key only accesses the company it was created for. Never expose it in client-side code.
Endpoints
All v1 endpoints require the Authorization header. JSON in and out. The feed URL is public (token in path).
GET /api/v1/organization
Score, review count, and widget URLs
GET /api/v1/invites
Quota and recent invites
POST /api/v1/invites
Create and optionally email invites
GET /api/v1/reviews
List published reviews (pagination)
GET /api/v1/products
List products
POST /api/v1/products
Create product (Commerce/Pro)
PATCH /api/v1/products/{id}
Update product IDs (gtin, sku, brand, mpn)
POST /api/v1/commerce/shopify/orders
Shopify order webhook → invite
POST /api/v1/commerce/woocommerce/orders
WooCommerce order webhook → invite
GET /feeds/{token}/product-reviews.xml
Google product reviews XML (public, token)
Organization
Returns RanqaScore, average rating, review count, and ready widget links.
GET https://ranqa.me/api/v1/organization Authorization: Bearer rnq_…
{
"id": "…",
"name": "Example AB",
"slug": "example-ab",
"primaryDomain": "example.com",
"plan": "pro",
"ranqaScore": 4.6,
"averageRating": 4.4,
"reviewCount": 128,
"publicUrl": "https://ranqa.me/example.com",
"widgets": {
"badge": "https://ranqa.me/widget/example-ab?type=badge",
"mini": "https://ranqa.me/widget/example-ab?type=mini",
"carousel": "https://ranqa.me/widget/example-ab?type=carousel",
"gallery": "https://ranqa.me/widget/example-ab?type=gallery",
"collect": "https://ranqa.me/widget/example-ab?type=collect",
"quote": "https://ranqa.me/widget/example-ab?type=quote"
}
}Invites
Send invites after delivery or purchase. Free plans have a monthly quota; Growth and Pro are unlimited.
Create invites
POST https://ranqa.me/api/v1/invites
Content-Type: application/json
Authorization: Bearer rnq_…
{
"recipients": [
{
"email": "[email protected]",
"name": "Anna",
"orderId": "ORD-123",
"productId": null,
"verifiedPurchase": true
}
],
"sendEmail": true
}verifiedPurchase: true applies the Verified customer badge. Use only with an order/CRM link. Misuse may revoke the key.
Alternative short form with emails[]:
{
"emails": ["[email protected]", "[email protected]"],
"verifiedPurchase": false,
"sendEmail": false
}List invites and quota
GET https://ranqa.me/api/v1/invites Authorization: Bearer rnq_…
{
"quota": { "used": 42, "limit": null, "remaining": null },
"invites": [
{
"id": "…",
"email": "[email protected]",
"verifiedPurchase": true,
"used": false,
"expiresAt": "2026-08-15T00:00:00.000Z"
}
]
}Reviews
List published reviews. Use nextCursor as cursor for the next page.
GET https://ranqa.me/api/v1/reviews?limit=20&rating=1&target=company Authorization: Bearer rnq_…
Query: limit (1–100), cursor (ISO date), rating (1–5), target (company|product).
{
"reviews": [
{
"id": "…",
"rating": 5,
"title": null,
"body": "Fast delivery",
"authorName": "Anna",
"source": "invite",
"language": "sv",
"createdAt": "2026-07-30T12:00:00.000Z"
}
],
"nextCursor": "2026-07-29T10:00:00.000Z"
}Products
Product pages and product invites require Commerce or Pro. POST creates a product under your company. Include gtin/brand/mpn for the Google feed.
GET https://ranqa.me/api/v1/products Authorization: Bearer rnq_…
POST https://ranqa.me/api/v1/products
Content-Type: application/json
Authorization: Bearer rnq_…
{
"name": "Vitamin D 90 caps",
"sku": "VD-90",
"externalId": "shopify-123",
"gtin": "0735001234567",
"brand": "Example",
"mpn": "VD-90-MPN",
"imageUrl": "https://cdn.example.com/vd.png"
}Shopify & WooCommerce
HTTP starters: point your store’s order webhook at Ranqa with a Commerce or Pro webhook token or API key.
POST https://ranqa.me/api/v1/commerce/shopify/orders
Authorization: Bearer rnq_…
Content-Type: application/json
{ /* Shopify order webhook JSON */ }POST https://ranqa.me/api/v1/commerce/woocommerce/orders
Authorization: Bearer rnq_…
Content-Type: application/json
{ /* WooCommerce order webhook JSON */ }Map Shopify product_id / Woo product_id to products.externalId so product invites link correctly.
Product reviews feed
Public XML (Google schema 2.4) for Merchant Center scheduled fetch. Create a token under Dashboard → API.
GET https://ranqa.me/feeds/{token}/product-reviews.xmlRotate the token if the URL leaks. Google approves the feed separately.
Widgets (iframe)
No API key needed for embeds — widgets are public. Pick a type and optional product slug. Snippets are in the dashboard.
<iframe
src="https://ranqa.me/widget/{slug}?type=badge&size=md"
width="280"
height="64"
style="border:0;overflow:hidden;border-radius:999px"
title="RanqaScore"
loading="lazy"
></iframe>Types: badge (size=sm|md|lg), mini, carousel, gallery, collect, quote. Badge shows a quality word when the score is high, with the Ranqa mark. Optional &accent=&star= hex colours. Add &product={slug} for a product page (collect links to reviews — product ratings require a purchase invite). Dashboard → Widget gallery has previews.
https://ranqa.me/widget/{slug}?type=badge&size=sm # email / compact
https://ranqa.me/widget/{slug}?type=badge&size=md # website (default)
https://ranqa.me/widget/{slug}?type=badge&size=lg # large
https://ranqa.me/widget/{slug}?type=mini
https://ranqa.me/widget/{slug}?type=carousel
https://ranqa.me/widget/{slug}?type=gallery
https://ranqa.me/widget/{slug}?type=collect
https://ranqa.me/widget/{slug}?type=quote
https://ranqa.me/widget/{slug}?type=carousel&product={productSlug}
https://ranqa.me/widget/{slug}?type=collect&product={productSlug}Webhooks
Register HTTPS endpoints in the dashboard for signed calls when reviews are created, flagged, or invites completed.
Events you can subscribe to:
review.created review.flagged invite.completed
Verify X-Ranqa-Signature = HMAC-SHA256 (hex) of the raw JSON body with your secret.
X-Ranqa-Signature: <hex hmac-sha256 of raw body>
{
"type": "review.created",
"reviewId": "…",
"organizationId": "…",
"rating": 2,
"status": "published"
}Endpoints are created in the dashboard (session), not via the v1 API key.
Error codes
Responses are JSON with an error field. Validation errors often include details.
401 Unauthorized — missing or invalid API key 403 Forbidden — plan/quota restriction 400 Bad Request — validation error (Zod details) 429 Too Many Requests — rate limited 500 Server error
Invite a clear share of customers — not only happy ones. Ranqa shows publicly how many reviews come from invites.
API FAQ
- Is public reviews JSON the same as the Pro API?
- No. GET /api/public/{slug}/reviews needs no key and is read-only. Pro Bearer endpoints under /api/v1/* require a paid plan key for invites, products, and writes.
- Can I use an API key in browser JavaScript?
- No. Keep rnq_ keys server-side. Widgets and public JSON are for client-facing reads.
- Where should AI assistants start?
- Prefer company/PDP pages, public JSON, https://ranqa.me/llms.txt, and https://ranqa.me/agents.md. Paid invite flows: this page and https://ranqa.me/integrations.