Reviews
Requires scope merchant-reviews-read.
Lists only this installed app’s imported reviews for this store, newest ingested first with cursor pagination. Approved imports remain unverified and are hidden from verified-only storefront blocks, store-wide summaries and testimonials unless the merchant opts in with verified_only=0. Customer product review lists, per-product summaries and latest-approved reviews include approved imports. Every review of the store, including shopper reviews, is read with product-reviews and its own scope. Imports are capped at 30 requests/minute and 2,000/day per installation, and 5,000 pending rows per app/store; 409 conflicts may be retried after 1 second.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Only items belonging to this product.
length <= 255Only items with this status. One of pending, approved, rejected.
Value in
- "pending"
- "approved"
- "rejected"
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/reviews?limit=2&starting_after=eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0wMyAwOTowMDowMCIsImlkIjoiMDE5YTFkNTItM2M4ZS03ZjQxLWIwZDItNmEzZTljMWY0YjIxIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ&status=pending" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "source_review_id": "example-channel-review-2026-0042", "source": "example-channel", "author_display_name": "Jordan Lee", "product_p_id": 20417, "rating": 5, "title": "Fresh and delicious", "description": "The chicken arrived hot.", "media": [], "status": "pending", "is_verified_purchase": false, "submitted_at": "2026-09-24T13:05:00+00:00", "created_at": "2026-10-03T08:00:00.000000Z", "edited_at": null } ], "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0wMyAwOTowMDowMCIsImlkIjoiMDE5YTFkNTItM2M4ZS03ZjQxLWIwZDItNmEzZTljMWY0YjIxIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-reviews-import.
Imports up to 100 reviews per request into pending moderation. Product references accept this store’s p_id, UUID or slug. The app identity and source are derived from the installation; re-import is idempotent by source_review_id. Approved imports contribute to product ratings but are not verified purchases. Limits: 30 requests/minute and 2,000/day per installation, plus 5,000 pending rows per app/store. Product resolution/mismatch, pending-cap 422 and 409 conflict attempts count toward quota; malformed payloads rejected by request validation do not. A 409 identity race includes Retry-After: 1; 429 responses include Retry-After seconds until the minute or daily window resets.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/reviews/import" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "reviews": [ { "source_review_id": "example-channel-review-2026-0042", "product": "20417", "rating": 5, "title": "Fresh and delicious", "description": "The chicken arrived hot.", "author_display_name": "Jordan Lee", "submitted_at": "2026-09-24T13:05:00+00:00", "media": [ "https://northwindgoods.example/reviews/2026-0042.jpg" ] } ] }'{ "status": "success", "message": "Product reviews imported", "data": { "results": [ { "source_review_id": "example-channel-review-2026-0042", "result": "imported", "status": "pending", "product_p_id": 20417 } ] }}Requires scope merchant-product_reviews-read.
Lists every review of the store’s products in any moderation state, newest first, with cursor pagination (limit + starting_after, has_more/next_cursor). Filter by status (pending, approved, rejected), rating (1 to 5) and product (p_id, UUID or slug of this store; an unknown product answers 422). Each review has its id (a UUID), product (id, slug, title), rating, title, description, media, status, is_verified_purchase, reviewer, source (the slug of the app that imported it, null for a shopper’s own review), the store’s response and responded_at, and submitted_at, created_at and edited_at. reviewer is the shopper’s first name and the initial of the rest (for example Chiamaka O.); the full name, avatar, email, phone and order are never returned.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Only items with this status. One of pending, approved, rejected.
Value in
- "pending"
- "approved"
- "rejected"
- null
Only items with this star rating, 1 to 5.
1 <= value <= 5Only items belonging to this product.
length <= 255Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/product-reviews?limit=2&status=approved&rating=4" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b30", "product": { "id": 20417, "slug": "smokehouse-party-pack", "title": "Smokehouse Party Pack" }, "rating": 4, "title": "Great party pack", "description": "Fed twelve of us and nobody complained.", "media": [], "status": "approved", "is_verified_purchase": true, "reviewer": "Alex M.", "source": null, "response": null, "responded_at": null, "submitted_at": null, "created_at": "2026-10-02T18:30:00+01:00", "edited_at": null } ], "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0wMiAxODozMDowMCIsImlkIjoiMDE5YTFkNTItM2M4ZS03ZjQxLWIwZDItNmEzZTljMWY0YjMwIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-product_reviews-read.
Retrieves one review of the store’s products by its id. The same object as the list; an id of another store or one that does not exist answers 404.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the product review, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/product-reviews/019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b30" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Review retrieved", "data": { "id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b30", "product": { "id": 20417, "slug": "smokehouse-party-pack", "title": "Smokehouse Party Pack" }, "rating": 4, "title": "Great party pack", "description": "Fed twelve of us and nobody complained.", "media": [], "status": "approved", "is_verified_purchase": true, "reviewer": "Alex M.", "source": null, "response": null, "responded_at": null, "submitted_at": null, "created_at": "2026-10-02T18:30:00+01:00", "edited_at": null }}Requires scope merchant-product_reviews-respond.
Publishes the store’s public reply to a review, up to 2,000 characters; sending another reply replaces the previous one. The reply shows on the storefront beside the review under the store’s name, so only send text the merchant has approved. It does not change the review’s status or the product rating. Answers the review.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the product review, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Publishes the store's reply to a review: the same rules as the merchant dashboard.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/product-reviews/019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b30/response" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "response": "Thank you, Alex. See you at the next party!" }'{ "status": "success", "message": "Review response saved", "data": { "id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b30", "product": { "id": 20417, "slug": "smokehouse-party-pack", "title": "Smokehouse Party Pack" }, "rating": 4, "title": "Great party pack", "description": "Fed twelve of us and nobody complained.", "media": [], "status": "approved", "is_verified_purchase": true, "reviewer": "Alex M.", "source": null, "response": "Thank you, Alex. See you at the next party!", "responded_at": "2026-10-03T09:00:00+01:00", "submitted_at": null, "created_at": "2026-10-02T18:30:00+01:00", "edited_at": null }}Requires scope merchant-product_reviews-moderate.
Sets a review’s status: approved shows it and counts it in the product rating and the store’s review summaries, rejected hides it, pending holds it back; the product rating is recalculated at once. The same states and rules as the merchant dashboard, for any review of the store including shopper reviews and reviews other apps imported. Answers the review.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the product review, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Sets a review's moderation status: the same rules as the merchant dashboard.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/product-reviews/019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b30/status" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "status": "approved" }'{ "status": "success", "message": "Review status updated", "data": { "id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b30", "product": { "id": 20417, "slug": "smokehouse-party-pack", "title": "Smokehouse Party Pack" }, "rating": 4, "title": "Great party pack", "description": "Fed twelve of us and nobody complained.", "media": [], "status": "approved", "is_verified_purchase": true, "reviewer": "Alex M.", "source": null, "response": null, "responded_at": null, "submitted_at": null, "created_at": "2026-10-02T18:30:00+01:00", "edited_at": null }}Requires scope merchant-review_settings-read.
Reads the switch for Queek’s own review request. review_requests_enabled true means Queek emails a customer two days after their order is delivered, asking them to review what they bought; a store that never set it reads true. Switch it off with PATCH review-settings before an app sends its own review request on orders/fulfilled, so a shopper is not asked twice. No webhook announces a change to it, so read it again when unsure.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/review-settings" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Review settings retrieved", "data": { "review_requests_enabled": false }}Requires scope merchant-review_settings-update.
Turns Queek’s own review request on or off: send review_requests_enabled (a boolean, required). True means Queek emails a customer two days after their order is delivered, asking them to review what they bought; false stops every request not yet sent, including those for orders delivered in the last two days, because Queek checks the switch when the email is due. It is the same switch the merchant sees in the dashboard settings, so the merchant can turn it back on there. Switch it off before an app sends its own review request on orders/fulfilled, so a shopper is not asked twice. Answers {review_requests_enabled}. No webhook announces a change to it. Send an Idempotency-Key so a retried call replays the first answer.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Turn automatic review requests on or off for the store.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/review-settings" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "review_requests_enabled": false }'{ "status": "success", "message": "Review settings updated", "data": { "review_requests_enabled": false }}