Product reviews

Build a reviews workflow around your products and moderation rules. Customers submit a rating and written review after signing in. You approve what appears, and the theme renders approved reviews from Shopify without calling Littleworks on every page view.

Use Littleworks to build a reviews section for my Shopify store. Let signed-in customers review products they purchased, with merchant approval before publication. Store submissions in Littleworks and publish approved review content to Shopify for Liquid rendering. Read https://littleworks.app/docs/recipe-reviews.md and adapt it to my store and theme.

What you are building#

• A product-page review display and a signed-in submission form with a 1–5 rating, public display name, and written review.
• Purchase verification and a pending state. The customer gets a receipt, not an immediate public post.
• A merchant-controlled approval and withdrawal workflow through private works. Littleworks Data lets you inspect submissions; it is not a built-in moderation editor.

Where the data lives#

The submission is the workflow authority; the Shopify entry is its public projection. Keep email addresses, order IDs, customer IDs, and moderation notes out of that projection. Define who edits published text: this recipe routes changes through the moderation work so a later publication cannot silently overwrite a merchant’s independent Shopify edits.

Shopify storage is a choice for this theme-focused recipe. If reviews need richer filtering through your own frontend, keeping approved reviews in Littleworks and serving a paginated public endpoint can also fit. That version spends runs on reads and needs an explicit public-field projection; it must never expose the submissions collection wholesale.

Before you build#

• Read Customer access and verify the storefront login supplies a customer ID through the installed app proxy. Do not accept a customer ID supplied by the browser.
• Use the Shopify permissions page for the minimum grants. The described runtime needs read_orders for purchase checks, write_metaobjects for publication, and write_products if it writes product metafields. Creating definitions through Littleworks additionally needs write_metaobject_definitions. Use get_context to verify the actual grants; write access includes the corresponding read access.
• Choose the purchase window and rules for refunds or cancelled orders. Shopify normally limits order access to the last 60 days; older-order access and protected customer data have separate requirements. Littleworks does not currently offer read_all_orders. Never label an unverified submission as a verified purchase.
• Use an unpublished theme for the display and form. Shopify resources are shared across Preview and Live: use distinct test definitions/handles and test products for publication checks.

The works to build#

Keep the works in feature reviews and the same environment. Create a uniqueness rule for orderId + productId if the merchant chooses one review per purchased product per order. Apply it once during setup in both intended environments. Specify a bounded input schema: valid IDs, integer rating from 1 to 5, display name up to 80 characters, and text up to 4,000 characters. Product and order IDs remain untrusted until checked against Shopify.

Implementation outline for the agent#

1. Define the Shopify content first. Inspect existing definitions and preserve unrelated data. Create a merchant-owned review definition with typed public fields and storefront access, plus a product metafield referencing a bounded list of those entries. Merchant-owned definitions are created at runtime through Admin GraphQL; they do not require editing Littleworks’ shared app TOML. If using publishable capability, keep unpublished entries in draft.
2. Accept and verify. Route the form to the deployed customer endpoint through the installed proxy. Get identity from context.customer.id. Query the supplied order with shopify.admin.graphql, verify its customer and product line items, and apply the chosen eligibility rules. Check GraphQL errors, paginate order lines when necessary, and fail closed when access or evidence is incomplete. Store only the needed fields as pending; never accept status or verifiedPurchase from input.
3. Moderate and write. A private work checks the submission revision and permitted state transition. Use metaobjectUpsert with a deterministic handle derived from the submission ID and environment to write only approved public fields. Write product references with metafieldsSet, preserving existing references and using compare-and-set protection. Make an approved entry active when publishable capability is enabled.
4. Handle partial publication. Littleworks and Shopify writes are not one transaction. Track the publication stage and returned Shopify ID. Inspect existing effects after a timeout; resume from the saved state rather than creating another review or incrementing a count again. Re-read and reconcile concurrent changes. Add a bounded private repair work if the build needs reconciliation; no scheduled repair is supplied.
5. Read in Liquid. Load the product metafield references and render each public metaobject field. Escape user-written text. Honor draft/active visibility and test the published access configuration. Withdrawal must remove visibility and update references; a successful private status change alone does not remove already published content.

Shopify references: merchant-owned definitions, metaobjects in Liquid, and metafields in Liquid. Validate the actual Admin operations against the current schema before deploying them.

Keep the storefront fast#

Do not scan every review in the store from Liquid or grow one product-reference list indefinitely. This first version displays a bounded set per product; define that limit and the behavior when it is reached. A larger review archive needs a separate pagination/index design. If adding rating summaries, make them reflect the intended set of approved reviews and reconcile them after approval, edits, or withdrawal; do not blindly increment on a retried publication.

Acceptance checks#

• A signed-out request fails. Customer A cannot submit a review for customer B’s order, an unrelated product, or an ineligible purchase.
• Double submissions do not create two reviews for the same allowed purchase. Concurrent moderator actions cannot silently overwrite each other.
• Pending and rejected reviews never appear publicly. Approval exposes only approved fields; withdrawal removes the visible entry.
• A failed Shopify write can be reconciled without duplicate publication. Existing product references survive concurrent updates.
• The theme still displays published reviews when the Littleworks submission work is paused. Submission errors and traffic limits produce useful messages.

Make it yours#

Add merchant replies, different eligibility rules, or a guest invitation flow using action tokens. Invitations need an authorized delivery mechanism; email sending, order-triggered invitations, review imports, and file uploads are not part of this recipe. Do not promise automatic reminders or Shopify event triggers.