Integrate a reviews platform

Overview

This resource will help you as you build an integration between a reviews or user-generated-content (UGC) platform and Klaviyo. It walks through why review data belongs in Klaviyo, the recommended integration flow, the review events to send, the reviewer profile properties to sync, and the authentication and certification requirements, with an API quick reference at the end.

Why connect your reviews platform to Klaviyo

Reviews are the highest-signal content a brand has about both its products and its customers. A review tells you who is engaged enough to advocate, who just had a bad experience, and which products are earning trust. The brands that get the most out of reviews don't leave that data locked in a widget. They push it into the platform where they run every other channel. When that platform is Klaviyo and review data lives there natively, you get measurable wins:

• Ask for reviews at the right moment, in the merchant's own flows. A merchant can trigger a review request off their existing post-purchase or fulfillment flow, with the same timing and segmentation logic they already use for email and SMS.
• Branch on sentiment automatically. A positive review is a referral and social-proof opportunity; a negative review is a support save. Splitting the follow-up on rating is the single highest-value review use case.
• Turn UGC into campaign content. Photo and video reviewers are a segment. Their content becomes dynamic blocks in newsletters and browse-abandonment flows.
• Segment on reviewer behavior. Repeat reviewers, five-star advocates, and customers who never review are all distinct audiences a merchant can target once reviewer data is on the profile.
• Stickier merchants. Reviews wired into flows and segmentation are one of the strongest retention signals across the partner program.

Short version: review events and reviewer state from your platform into the Klaviyo profile mean the merchant's marketing team can act on review activity from the same place they run every other channel.

The flow

One-way push, partner to Klaviyo. Reviews are event-driven. The value is in the moment a review is requested, submitted, or published, so events are the heart of this integration:

• Event emission for every review moment. Review requested, review submitted, review published, photo review submitted, question answered. These are the metrics the merchant builds segments and flows against.
• Profile property sync (optional) for reviewer state. Review count, average rating given, last review date. Written inline on the event so a single call covers both streams.

Both fire in real time as the underlying activity happens in your platform. Each profile is keyed by email first, with phone where you support SMS review requests. Use the merchant's customer ID as external_id where it's stable, but always identify by email first.

The review-request moment is almost always tied to order fulfillment or delivery. Fire your Review Requested event when your platform's request condition is met, and document that condition clearly so merchants know what triggers it. On initial install, no historical backfill of past reviews is needed for most use cases; reviews are forward-looking. If you backfill reviewer state (counts, average rating) for immediate segmentation value, use the bulk profile import job for the roll-up properties only, not historical review events.

Events to send

Event names are not prefixed with your platform name. Branded events handle source attribution automatically when events flow through your OAuth token, so the metric name should just describe the action. Use Title Case payload field names ("Review Title", "Verified Purchase") so they read cleanly in the Klaviyo property picker and template editor.

Review lifecycle events

The Positive / Negative pair is the highest-value branch point in the whole integration: it's what lets a merchant route a happy customer to a referral ask and an unhappy one to a support save. Emit both alongside the general Review Submitted event so merchants can build flows on whichever granularity they prefer.

$value guidance: review events do not carry revenue; they're feedback and content events, not transactions. Don't set $value. The one exception to consider is if a review submission issues a reward or coupon (a "review for a discount" incentive); that reward event could carry the coupon's value, mirroring how the loyalty guide treats a reward. Treat that as a judgment call, not a default.

How merchants use it

• Post-fulfillment review request. Trigger a request flow off the merchant's Fulfilled Order metric (or your Review Requested event) a set number of days after delivery.
• Sentiment-branched follow-up. Positive Review Submitted → thank-you plus a referral or social-share ask; Negative Review Submitted → a support or win-back flow before the review goes public.
• UGC in campaigns. Segment on Photo or Video Review Submitted, then use the review content and photo URLs as dynamic blocks in newsletters and flows.
• Re-request suppression. Use Review Submitted (or the Last Review Date property) as a flow filter so merchants don't re-ask someone who already reviewed.

Profile properties to sync (optional)

Optional, written inline on any event. Use Title Case property names prefixed with your platform's name. Replace {Platform} below with the literal name of your platform (e.g., "Acme Average Rating Given"). These give the merchant a current-state view of each reviewer for segmentation.

Implementation notes:

• Profile property writes go through Update Profile (PATCH /api/profiles/{id}/), or are written inline on Create Event (POST /api/events/). Inline on the event is the right default.
• Pick property names up front and don't rename them. Renames break every segment, flow, and template that references them.
• Keep dates in ISO 8601 (UTC). Klaviyo treats string-typed dates as strings, which silently breaks date-property segmentation.
• Don't overwrite core profile identity (name, phone, address) from your platform. The merchant's commerce integration owns that; stick to your namespaced reviewer properties.

Auth, scopes, and certification

Build as a public OAuth app. Private API keys are a non-starter for the marketplace. Start with the Create a public OAuth app guide.

Key OAuth specifics for reviews integrations:

• PKCE is required on the authorization code exchange (code_verifier must be included).
• Access tokens are short-lived (1 hour). Refresh tokens are long-lived but rotate on every use. Persist the latest refresh token after every refresh call, or you'll lose the integration on the next refresh.
• Tokens are scoped per Klaviyo account. Merchants with multiple Klaviyo accounts (brands, regions, prod and test) install separately for each.

Scopes to request:

• events:write to emit review lifecycle events. This is the core scope.
• profiles:write to write the optional reviewer properties to profiles.
• profiles:read only if you match or dedupe an existing profile before sending a request. Most reviews integrations don't need this.
• catalogs:read only if you resolve product data (name, image, URL) from the merchant's Klaviyo catalog rather than your own product cache.

Don't over-scope. Unused scopes get flagged in marketplace review. Branded metric badges happen automatically when events flow through the OAuth token. No extra payload field is needed.

Once functional, submit for App Marketplace review under the Reviews category. Plan for at least one round of feedback. The review covers OAuth, scopes, install and uninstall validation, and that the integration delivers what your listing claims.

API quick reference

Concrete specs for AI coding assistants and engineers grounding on this doc. The narrative above is the why and the flow. This section is the what-to-actually-type.

Headers (required on every request)

Authorization: Bearer <oauth_access_token>
revision: 2026-04-15
Accept: application/json
Content-Type: application/json

Pin the revision header to a specific date when you ship. Check the API versioning guide for the current latest. Without it you'll get a 400.

Event POST body

Send a review event. The event creates the profile if it doesn't exist, and updates the optional reviewer properties on the profile inline. Identify by email first.

POST /api/events/

{
  "data": {
    "type": "event",
    "attributes": {
      "properties": {
        "Review ID": "rev_55210",
        "Rating": 5,
        "Review Title": "Best bar soap I've used",
        "Review Content": "Great lather and the scent lasts.",
        "Product Name": "Cedar Bar Soap",
        "Product URL": "https://yourbrand.com/products/cedar-bar-soap",
        "Has Photo": true,
        "Verified Purchase": true
      },
      "time": "2026-06-17T14:22:11Z",
      "unique_id": "rev_55210",
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Positive Review Submitted" }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "[email protected]",
            "properties": {
              "{Platform} Review Count": 3,
              "{Platform} Average Rating Given": 4.7,
              "{Platform} Last Review Date": "2026-06-17T14:22:11Z",
              "{Platform} Last Review Rating": 5
            }
          }
        }
      }
    }
  }
}

Include time (when the event occurred, ISO 8601) and unique_id (a stable identifier for the event) on every event. Klaviyo uses unique_id to deduplicate, so set it to a value that's stable for that occurrence, such as your review ID.

Retries

• 429: respect the Retry-After header. Otherwise exponential backoff starting at 1s, cap at 60s, max 5 retries.
• 5xx: same backoff.
• 4xx (other than 429): don't retry. Log and surface to the merchant.

Identifier guidance

• Identify by email first; phone where you support SMS review requests. These are the fields Klaviyo merges on.
• external_id is NOT a merge key on its own. Pass it alongside email and store the merchant-side customer ID as a profile property for segmentation.
• Don't identify or merge profiles on anything other than email or phone.

Rate limits

Per-account, not per-app. Standard limits handle typical review volume without effort. For merchants at unusual scale, or for a large historical backfill at install, batch with Bulk Create Events (POST /api/event-bulk-create-jobs/) and reserve POST /api/events/ for the real-time hot path. Request per-endpoint, per-account increases through Klaviyo Support and CSM before launch rather than ramping into 429s in production.

Glossary

• Klaviyo profile: customer record. Keyed by email, phone, or external ID. For a reviews integration, the reviewer.
• Klaviyo metric: event type. "Review Submitted," "Photo Review Submitted," etc. Created automatically on first event ingest.
• Klaviyo segment: dynamic audience computed from rules. The merchant builds these from your review events and properties to target reviewers.
• Klaviyo flow: automated journey, triggered by a metric (event) or segment membership. Where review-request and sentiment-branched follow-ups live.
• UGC: user-generated content. Photos and videos submitted with a review, often reused as marketing content.
• Sentiment threshold: the star rating (commonly 4) that splits a positive review from a negative one and branches the follow-up.
• Verified purchase: a review from a customer whose order your platform can confirm, versus an unverified reviewer.

Resources

• Klaviyo Developer Portal. Start here for everything.
• Create a public OAuth app
• Create Event / Bulk Create Events / Update Profile
• Klaviyo App Marketplace, Reviews category. The existing set of reviews integrations.
• App Marketplace Review: [email protected]