Shopify Reviews API Integration Reference

Overview

This document details the integration of the Shopify App Bridge Reviews API into the application. This feature allows the app to prompt merchants for a review directly within the Shopify Admin interface when specific eligibility criteria are met.

Feature Logic

Eligibility Criteria

The review prompt is triggered ONLY if the following conditions are satisfied:

1. Installation Age: The app must have been installed for at least 96 hours (4 days).
2. Platform Usage: The merchant must have at least one active Pricing Rule created more than 7 days ago.
3. Shopify Rate Limits: Shopify internally manages frequency and may suppress the prompt if the merchant has been asked recently (by any app) or has already reviewed the app.

Data Tracking

To support these criteria, we track specific milestones in the database:

• ShopSettings Model:
  • installedAt: Timestamp of app installation (or first detected launch).
  • firstBillingSuccessAt: (Placeholder) Timestamp for future billing triggers.

Technical Implementation

Database Schema (prisma/schema.prisma)

A dedicated model ShopSettings handles app-wide configuration and lifecycle events:

model ShopSettings {
  shop                    String    @id
  installedAt             DateTime  @default(now())
  firstBillingSuccessAt   DateTime?
  reviewPromptLastShownAt DateTime?
  createdAt               DateTime  @default(now())
  updatedAt               DateTime  @updatedAt

  @@map("shop_settings")
}

Backend Service (app/services/reviews.service.ts)

The CheckReviewEligibility function performs the logic checks:

1. Retrieves ShopSettings for the current shop.
2. Auto-creates ShopSettings with installedAt = now() if missing.
3. Calculates hours since installation.
4. Queries the oldest PricingRule to determine usage duration.
5. Returns true only if all app-side checks pass.

Frontend Integration (app/routes/app.tsx)

The main app layout handles the actual API call:

1. Loader: Calls CheckReviewEligibility server-side.
2. Pass-through: Returns a showReviewPrompt boolean to the client.
3. Effect Hook:

   useEffect(() => {
     if (showReviewPrompt && window.shopify?.reviews?.request) {
       window.shopify.reviews.request();
     }
   }, [showReviewPrompt]);

   Note: Uses App Bridge v4 window.shopify global.

Testing & Verification

To verify the integration in a development environment (where natural timeframes are impractical), use database manipulation scripts.

Verification Script Logic

Since reviews.request() behavior varies by environment, verifying the trigger logic is the primary goal.

Scenario: Eligible

// Pseudo-code for DB Update
await prisma.shopSettings.update({
  where: { shop: SHOP_DOMAIN },
  data: { installedAt: FIVE_DAYS_AGO }
});
await prisma.pricingRule.create({
  data: { createdAt: EIGHT_DAYS_AGO, ... }
});

Scenario: Ineligible (Reset)

await prisma.shopSettings.update({
  where: { shop: SHOP_DOMAIN },
  data: { installedAt: NOW }
});

Expected Behavior

• Eligible: [Reviews] Triggering review prompt appears in the browser console.
• Ineligible: Server logs indicate Shop <shop> installed Xh ago (wait 96h).