> ## 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 → Install**, 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. One more block goes on product pages: | Block | Where | Shows | | - | - | - | | **Boom review highlights** | Product page | A card for the buy box: the AI summary and its topics (when you show it), your best quote and a link down to the reviews section. Hidden on products without reviews. | These blocks show reviews from across your store: | Block | Where | Shows | | - | - | - | | **Boom reviews carousel** | Any page | Reviews side by side: the ones you featured (or your 5-star reviews while you haven't featured any), 5-star reviews, those with photos, or the newest. Cards with a photo or quote only, or a wall of quotes. 12 by default; your featured reviews show at most 12. | | **Boom review wall** | Any page | A masonry wall of reviews and their photos, with an "All / With photos" filter and "Load more reviews". | | **Boom testimonials** | Any page | One large quote at a time with its author and product, arrows and dots. It can move on its own. | | **Boom photo gallery** | Any page | Your shoppers' photos, newest first, each with its rating. A photo opens with its review and a link to the product. | | **Boom rating banner** | Any page | Your average rating and review count, as a band with up to three short quotes or as one line that links to your reviews page. | | **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. In the theme editor you also choose which products a block covers (all, a collection's first 50 products, or products you pick) and, for the carousel and testimonials, how many reviews it shows (up to 24; featured reviews stop at 12); the banner takes the page its one-line style links to. How a block looks and which reviews it picks are set in Boom (see below). 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 block says why it's empty; your shoppers see nothing until there is something to show. Moving widgets (the carousel and testimonials, when set to move on their own) stop while a shopper hovers or is inside them, have a pause button, and stay still for shoppers who ask their device for reduced motion. ### Choose the look **Reviews → Widgets** shows each widget on sample reviews, at desktop or phone width and on a light or dark theme, while you change it. Your changes reach your store when you choose **Publish to store**, within a few minutes. Start with the **store look**, which every widget follows: * **Style:** start from a preset (Editorial, Minimal, Soft or Bold), then pick the star color (or your theme's text color), corners, how reviews are framed (lines, outlines or filled cards) and whether headings use your theme's heading font. * **Content:** turn the AI summary, the row of customer photos, photos in reviews, the verified-buyer mark, reviewer initials, review dates and your replies on or off. * **Settings:** the default sort, and whether products without reviews show the section at all. Then pick a widget to give it a **custom look** (its own star color, corners, cards and headings) or to set what it does: * **Product reviews** and **All reviews:** the layout (summary beside the list, cards, or one column). * **Star rating:** three badge styles. * **Carousel:** which reviews, the card (photo on top, quote only, or a wall), cards per view on desktop, whether it moves on its own, and the product. * **Review wall:** which reviews, and the photo filter. * **Testimonials:** which reviews, whether it moves on its own, and the product. * **Rating banner:** a band with quotes, or one line. * **Review highlights:** the AI summary and the best quote. Widgets use your theme's fonts and colors; Boom loads no fonts. A review the buyer got something for always says so, whatever the look. 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 → Install → 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}
``` On a product page, `
` adds the highlights card. Add `data-heading="Your title"` to change a heading, or `data-heading=""` to hide it. On the carousel, wall, testimonials, gallery and banner, add `data-refs="ID1,ID2"` (up to 50 product ids) to show reviews of those products only. On the carousel and testimonials, add `data-max="8"` to show at most that many (up to 24; featured reviews stop at 12). The all-reviews element always covers your whole store. `data-link` takes a web address (`https://…`) or a path on your site. Elements 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 → 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. ## The AI summary on product pages Turn on **AI summary** in **Reviews → Widgets → Content** 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 → Follow-up**, 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 → Follow-up**). 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.