> ## Documentation Index > Fetch the complete documentation index at: https://docs.useboom.ai/llms.txt > Use this file to discover all available pages before exploring further. # Reviews > Collect product reviews on WhatsApp, moderate them, and show them on your store — Shopify or any website. Reviews asks your buyers for a review of what they bought, over WhatsApp, a few days after it arrives. Boom's agent asks about each product, saves the rating, their words and any photos, and the reviews go live on your store once they pass your publishing rules. Low ratings land in your team's inbox. Reviews is turned on per organization. If you don't see **Reviews** in the Boom app, ask your account manager. ## How it works 1. **Boom learns your orders.** From your connected Shopify store, or from the products and orders your store sends through Boom's API (below). 2. **Boom plans the asks.** Every hour, it picks the orders due for an ask (when they were placed, shipped or delivered, plus the days you choose), merges orders shipped close together, and keeps the ask to your most valuable products. Turn on **Shadow** first to see who would be asked without sending anything. 3. **The agent collects the reviews.** **Set up asks** creates a "Product reviews" initiative with a ready journey: the ask, a reminder, and the conversation. Pick your WhatsApp templates, launch it, and switch asks to **Live**. 4. **Your rules decide what's public.** Publish automatically unless the AI check flags something, only from a minimum rating, or always by hand. Photos can wait for a person even when the text is published. ## Show reviews on Shopify In **Reviews → Widgets**, choose **Connect**. Then, in your theme editor, turn on the **Boom Reviews** app embed and add the **Boom product reviews** and **Boom star rating** blocks to your product template. Three more blocks show reviews from across your store: | Block | Where | Shows | | - | - | - | | **Boom reviews carousel** | Any page | The reviews you featured in Boom, newest first, up to 12. Hidden until you feature one. | | **Boom photo gallery** | Any page | Your shoppers' photos, newest first. Hidden until a review has a published photo. | | **Boom all reviews** | A page template | Every published review with your store's rating summary, filters and paging. | Each has a heading you can change or hide. Left empty, the heading appears in your store's language. If you connect more than one Shopify store to Boom, each store's blocks show only that store's products. While you edit your theme, an empty carousel or gallery says why it's empty; your shoppers see nothing until there is something to show. Boom also keeps Shopify's standard product rating up to date on every product that has reviews, so theme product cards and Google Shopping can show stars, and adds the rating to each product page's structured data for Google search results. Turn the embed's **Star ratings in Google results** setting off if your theme already outputs ratings. ## Show reviews on any website In **Reviews → Widgets → Install on any website**, copy the code into your product pages: ```html theme={null}
``` The code in the app already carries your store's key. `data-product-ref` is the product's id: the same id you send Boom as the product's `externalId`. The script loads once however many elements a page has, so a list of products can show stars for each. The same script shows reviews from across your store anywhere on your site. These elements need no product id: ```html theme={null}
``` Add `data-heading="Your title"` to change a heading, or `data-heading=""` to hide it. The carousel and the gallery show nothing until there is something to show. On a website, these elements show reviews from every store you connect to Boom. The script looks for these elements once, when the page loads. Elements your site adds later, such as a single-page app rendering a new page without a full reload, aren't picked up. ## Send products and orders through the API A store that isn't on Shopify sends its catalog, buyers and orders to Boom's [CDP](/cdp/overview) with an [API key](/authentication). First, in **Reviews → Settings → Store data**, choose **Set up the commerce API**: it creates the two types below and the link from a person to their orders. | Type | `externalId` | Attributes | | - | - | - | | `commerce_product` | your product id (`data-product-ref`) | `title` (required), `url`, `imageUrl`, `handle`, `productType`, `tags` (list), `status`: `ACTIVE` or `ARCHIVED` | | `commerce_order` | your order id | `placedAt` (date-time, required), `name` (e.g. `#1001`), `fulfilledAt`, `deliveredAt`, `status`: `OPEN`, `PARTIAL`, `FULFILLED`, `CANCELLED` or `REFUNDED`, `currency`, `lineItems` (required list) | Each line item is `{ "id", "productId", "title", "variantTitle", "unitPrice" }`, where `id` and `productId` are required and `productId` is a `commerce_product` `externalId`. Boom asks about each line once, ever. * **Dates** are ISO 8601 date-times with a timezone, like `2026-10-01T15:00:00Z` or `2026-10-01T10:00:00-05:00`. A date alone (`2026-10-01`) isn't read, and an order without a readable `placedAt` is never asked about. * **Shipped time** is `fulfilledAt`. If you only know when the order arrived, `deliveredAt` alone counts as shipped too. * **Ids** (`externalId`, line `id`, `productId`) are strings. Keep them the same every time you send the order: a changed id reads as a new line, and Boom may ask about it again. * A line without a `title` uses the product's `title` in the ask. ```bash theme={null} export BASE="https://www.useboom.ai/api/v1/cdp" curl -X POST "$BASE/custom-objects" \ -H "Authorization: Bearer $BOOM_KEY" -H "Content-Type: application/json" \ -d '{ "type": "commerce_product", "externalId": "kit-viaje", "attributes": { "title": "Kit de viaje", "url": "https://tienda.example/kit-viaje", "imageUrl": "https://cdn.example/kit-viaje.jpg", "tags": ["viaje"] } }' ``` Boom asks on WhatsApp, so the person needs a phone number. ```bash theme={null} curl -X POST "$BASE/people" \ -H "Authorization: Bearer $BOOM_KEY" -H "Content-Type: application/json" \ -d '{ "externalId": "cliente-55", "firstName": "Lucía", "phoneNumber": "+5215512345678" }' ``` ```bash theme={null} curl -X POST "$BASE/custom-objects" \ -H "Authorization: Bearer $BOOM_KEY" -H "Content-Type: application/json" \ -d '{ "type": "commerce_order", "externalId": "web-1001", "attributes": { "name": "#1001", "placedAt": "2026-10-01T15:00:00Z", "fulfilledAt": "2026-10-03T12:00:00Z", "status": "FULFILLED", "currency": "MXN", "lineItems": [ { "id": "1", "productId": "kit-viaje", "title": "Kit de viaje", "unitPrice": 499 } ] } }' ``` Send it again whenever it changes (shipped, delivered, cancelled): the `externalId` makes the call an update. An update replaces the order's attributes, so send the whole order each time, or add `"mode": "merge"` to send only what changed: ```bash theme={null} curl -X POST "$BASE/custom-objects" \ -H "Authorization: Bearer $BOOM_KEY" -H "Content-Type: application/json" \ -d '{ "type": "commerce_order", "externalId": "web-1001", "mode": "merge", "attributes": { "status": "CANCELLED" } }' ``` Find the `placed` link once with `GET $BASE/relationship-types`: the entry with `role: "placed"` and `customObjectType: "commerce_order"` carries the `relationshipTypeId` to use. Then: ```bash theme={null} curl -X POST "$BASE/relationships" \ -H "Authorization: Bearer $BOOM_KEY" -H "Content-Type: application/json" \ -d '{ "relationshipTypeId": "PLACED_TYPE_ID", "personExternalId": "cliente-55", "customObjectExternalId": "web-1001" }' ``` When asks are timed from shipping or delivery, an order that is partly shipped (`PARTIAL`) waits until it's fully shipped; if it is still partial 30 days after it first shipped, Boom doesn't ask about it. Asks timed from the order date don't wait for shipping. A cancelled or refunded order is never asked about, and an ask whose orders were cancelled after it was planned is dropped before it's sent. A record Boom can't read (no readable `placedAt`, `lineItems` not a list) is skipped, every hour until it's fixed, and the rest are planned. ## Choose the look **Reviews → Widgets → Look** sets the star color and the corners, and whether to hide the section on products without reviews or show the "Verified buyer" label. The preview below the settings shows the product section or the carousel with sample reviews, at desktop or phone width, drawn by the same code your store runs. Everything else follows your site's font and colors. Turn on **Show the AI summary** to add what customers say to each product with 5 or more published reviews: a short summary and the topics shoppers mention, labelled as an AI summary of the reviews it read (the newest 60 at most). Boom writes it from the reviews' ratings and words, never their authors' names, writes it again after 5 more reviews or when reviews are removed, and takes it down when fewer than 5 published reviews remain. In **Reviews**, open a product to read its summary, keep it off your product pages, or have it written again. ## Reach shoppers by what they rated Boom keeps two numbers on each reviewed product in your CDP: `boom_reviews_rating` (the published average, one decimal, empty until the product has a published review) and `boom_reviews_count`. They update when a review changes, and your Shopify product syncs leave them in place. In **Segments**, they work like any product attribute: for a Shopify store, "people who bought a product rated below 3" is a person who **placed** an **order** whose **line item** references a **product** with `boom_reviews_rating` less than 3. For reviews Boom collects over WhatsApp, the person also gets a `review_submitted` event when they leave the review, with its `rating`, so "reviewed a product with 2 stars or less" works for any store. Imported and manually added reviews don't create that event. ## Thank photo reviews with a gift card In **Reviews → Settings**, turn on **Thank photo reviews with a gift card** and choose the amount. It needs a connected Tremendous account (**Settings → Rewards**). Then choose **Add to the journey**: Boom adds the reward step to a draft of your reviews journey. Publish the draft to start offering it; until then, buyers aren't offered anything. Sending gift cards in WhatsApp also needs your approved reward-delivery template, and the journey won't publish without it. Once the journey with the reward is published: * Boom's agent tells buyers that the store sends one gift card per order when they add a photo or video to a review, whatever their rating. It never offers anything else. * Each gift card waits for your approval in **Drafts** before it's sent. Approve every photo review's gift card whatever its rating: approving only happy buyers would make the reward depend on what they said, which consumer-protection rules forbid. * Reviews written with the reward show as **Incentivized review** on your store and in Boom. * To stop offering it, publish your journey without the reward step. ## When a buyer is unhappy Boom hands a review conversation to your team when the buyer's lowest rating is at or below your threshold (2 stars by default; choose 1, 2 or 3 stars in **Reviews → Settings**). Your team finds it in the inbox with a note of what was rated low, in the buyer's words, and the instructions you wrote in **What your team should do**. Boom's agent never offers anything itself. With **Notify the team in Boom** on, everyone in your organization sees a notification that opens the conversation. ## Bring reviews from another app **Reviews → Import** takes a CSV export from Judge.me or Revie, or any CSV with a column mapping. A dry run shows how many rows are ready, which products weren't found and which rows are duplicates before anything is saved. Imported reviews keep their date, rating and photos and publish straight away. ## Related People, custom objects and relationships: what the commerce API writes to. How links like `placed` are defined and found by id. The journey Set up asks creates, and how to adjust it. Create the API key the calls above use. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.