Settings API

Last updated: May 12, 2026

Get Settings

GET /api/v1/store/review-settings

{
  "settings": {
    "collection_enabled": false,
    "default_experience": "chat",
    "auto_moderation_preset": "manual",
    "review_request_trigger": "fulfilled",
    "review_request_delay_days": 7,
    "review_request_delivery_fallback_days": 14,
    "request_token_expiry_days": 90,
    "digest_enabled": false,
    "digest_recipient_email": null
  }
}

Update Settings

PUT /api/v1/store/review-settings

Pass only the settings you want to change.

{
  "settings": {
    "collection_enabled": true,
    "review_request_trigger": "fulfilled",
    "review_request_delay_days": 7
  }
}

Changing review_request_trigger or review_request_delay_days re-schedules every pending request matching the new trigger against the new delay. Requests whose new send time is now in the past fire on the next scheduler tick. Requests queued under a different trigger are left alone.

Setting Reference

Setting	Type	Default	Description
`collection_enabled`	boolean	false	When `true`, the configured Shopify order event (see `review_request_trigger`) automatically creates review requests.
`default_experience`	string	"chat"	`chat` (AI-guided conversation) or `form` (simple star + text).
`auto_moderation_preset`	string	"manual"	Controls automatic review publishing. `"manual"` requires merchant approval for all reviews. Other values — `"open"`, `"relaxed"`, `"balanced"`, `"careful"` — publish reviews that score above a preset threshold. Spam, abuse, and complaint reviews always require manual review regardless of preset. Changing this from `"manual"` to a non-manual preset triggers retroactive scoring of the BR-collected (`platform IN ('direct','public')`) pending backlog; imports are excluded.
`review_request_trigger`	string	"fulfilled"	Event that starts the send countdown: `"created"`, `"paid"`, `"fulfilled"`, or `"delivered"`. `"fulfilled"` and `"delivered"` fire per physical shipment (one email per fulfillment — split orders produce multiple emails, each scoped to its own products). `"created"` and `"paid"` fire per order. `"delivered"` uses Shopify's carrier-tracking delivery confirmation (requires the `read_fulfillments` scope via the Shopify app install). Invalid values clamp to the default server-side.
`review_request_delay_days`	integer	7	Days to wait after the trigger event before sending. Per-trigger caps: `fulfilled` 0–30 (recommended 3–14), `delivered` 0–30 (recommended 0–7), `created` 0–60 (recommended 7–30), `paid` 0–60 (recommended 7–30). Out-of-range values are clamped server-side.
`review_request_delivery_fallback_days`	integer	14	Only applies when `review_request_trigger = "delivered"`. If no carrier delivery confirmation arrives within this window, BetterReviews sends the email anyway (measured from fulfillment). Range 3–30. Default 14 balances carrier-signal latency against customer recall.
`request_token_expiry_days`	integer	90	How long each review-request link stays valid. Range 30–180.
`send_window_local_start`	integer	9	Earliest local hour to send review-request emails (in customer's resolved timezone). Range 0–23.
`send_window_local_end`	integer	21	Latest local hour (exclusive) to send. Range 1–24.
`send_time_strategy`	string	"even_jitter"	`"even_jitter"` spreads sends across 9–21 local with deterministic per-row jitter; `"off"` uses legacy time-of-trigger timing (no local-window adjustment).
`digest_enabled`	boolean	false	Weekly digest email with review stats.
`digest_recipient_email`	string	null	Override email for digest (defaults to store owner).
`auto_recharge_enabled`	boolean	false	Opt in to fair auto-recharge — BetterReviews auto-purchases extra AI-collected reviews when you exceed your plan's monthly limit. Reviews plan: $25 per 100 extras. Pro: $50 per 300. Enterprise: $100 per 1,000. First 10% of each period's overage is free. Tier is determined by your plan and cannot be set via this API — upgrade your plan for a bigger block at a lower per-review rate. Setting to `false` disables auto-recharge and flips `auto_recharge_state` to `"off"`.
`monthly_spend_cap_cents`	integer	20000	Maximum cents BetterReviews will spend on auto-recharge per billing period. Range 5000 ($50) to 100000 ($1,000). Freely settable inside this range — no Shopify approval required. The $1,000 ceiling is approved at install; the merchant cap is enforced locally.
`auto_recharge_state`	string (read-only)	"off"	Server-managed state machine: `"off"`, `"active"`, `"cap_reached"`, `"shopify_rejected"`. Read-only — flipped by BetterReviews based on settings + billing events. (The legacy `"pending_confirmation"` value is no longer reachable since auto-recharge enable became local-only in v3.)

Note on the legacy pending_overage_tier key: pre-v2, merchants picked a tier via this settings key. It has been removed — any PUT containing pending_overage_tier returns HTTP 422 with error: "pending_overage_tier_removed". Use auto_recharge_enabled instead.

Note on cap changes: as of v3 (2026-05-09), monthly_spend_cap_cents is freely settable within $50–$1,000 with no Shopify approval required. The legacy cap_increase_requires_resubscribe error is no longer returned.

Example Configurations

Manual only (no automation)

{
  "settings": {
    "collection_enabled": false,
    "digest_enabled": false
  }
}

Use /review-requests/send with skip_email: true to create links manually.

Fully automated (default trigger)

{
  "settings": {
    "collection_enabled": true,
    "review_request_trigger": "fulfilled",
    "review_request_delay_days": 7,
    "auto_moderation_preset": "balanced",
    "digest_enabled": true
  }
}

Automated collection, manual moderation, paid trigger

{
  "settings": {
    "collection_enabled": true,
    "review_request_trigger": "paid",
    "review_request_delay_days": 14,
    "auto_moderation_preset": "manual",
    "digest_enabled": true
  }
}

Delivered trigger with 3-day delay, tighter 10-day fallback (recommended for merchants with reliable carriers)

{
  "settings": {
    "collection_enabled": true,
    "review_request_trigger": "delivered",
    "review_request_delay_days": 3,
    "review_request_delivery_fallback_days": 10,
    "auto_moderation_preset": "relaxed",
    "digest_enabled": true
  }
}

Sends review requests 3 days after the carrier confirms delivery. If delivery is never confirmed (silent or offline carrier), falls back to sending 10 days after fulfillment instead — tighter than the default 14-day fallback, suitable when your carriers reliably report delivery.

Email Moderation Settings (admin extension)

Email-driven moderation lets a merchant's CS team approve / reply / archive pending reviews directly from their inbox. These settings are managed through the Shopify admin extension (App Bridge JWT), not the public API. The full endpoint reference lives in the betterreviews-api skill; the keys are summarized here for completeness.

Key	Type	Default	Description
`email_actions_enabled`	boolean	`false`	Master toggle for the entire email-driven moderation surface. When `false`, no notification emails fire and existing email-action links won't work.
`pending_notification_mode`	string	`"instant"`	`"instant"` sends a notification email per pending review (deduplicated on `(store_id, review_id)`). This is the resting default once `email_actions_enabled` is on. `"digest_only"` silences per-review sends and is reserved for the upcoming digest worker. `"off"` is equivalent to flipping `email_actions_enabled` off.
`auto_dm_from_email_action`	boolean	`true`	When `true`, approving a review from an email action fires the merchant's standard auto-thank-you DM via Shopify Flow's `review-created` trigger. When `false`, the DM is suppressed for all email-action approvals. The rep can additionally opt out per-review via a checkbox on the email confirmation page.

Recipient management (add / revoke / resend verification / list) and the Invalidate all pending notification links safety button are also admin-extension endpoints — they don't appear on the public API. Recipients are capped at 5 per store (active + pending verification combined), require one-time email-link verification before activation, and have their emails stored encrypted at rest and masked in the admin UI.