ShopSheets — Klaviyo integration testing instructions

Prerequisites

• A Klaviyo account you control with at least Manager role. The account should have at least one campaign or flow with recent activity to validate data retrieval.
• A Google account (used to log into ShopSheets and to host the destination Google Sheet).
• A web browser. No CLI or developer tools required.

If you need a ShopSheets reviewer account, email periel@wearegrowth.co and one will be provisioned within 1 business day.

Test 1 — Install (OAuth)

1. Visit https://shopsheets.io and sign in with Google.
2. On the Dashboard, click Add connection.
3. In the modal, select Klaviyo from the platform dropdown. The form should display the OAuth-style "Continue with Klaviyo" button (no manual API key entry).
4. Click Continue with Klaviyo. You will be redirected to Klaviyo's authorization page.
5. Expected: the Klaviyo consent screen lists the following scopes — accounts:read, campaigns:read, flows:read, forms:read, lists:read, metrics:read, profiles:read, segments:read, tags:read. All scopes are read-only.
6. Approve. Klaviyo redirects you to https://shopsheets.io/KlaviyoOAuthCallback?code=...&state=... and ShopSheets exchanges the code for tokens.
7. Pass criteria: the page shows "Klaviyo Connected" and you are returned to the Dashboard. The new connection appears in the connection list, labeled with your Klaviyo organization name.

Test 2 — Functionality (read campaign data)

1. Visit https://shopsheets.io/KlaviyoTerminal. Your Klaviyo connection from Test 1 should appear in the connection picker.
2. Set Query Level to Campaign performance.
3. Set Date Range to Last 30 days.
4. Check the dimensions Campaign name, Date.
5. Check the metrics Recipients, Opens, Clicks, Conversions.
6. Click Run Query.
7. Pass criteria: within 5–15 seconds, a results table renders with one row per (campaign, date) pair. Recipients / Opens / Clicks / Conversions match the same metrics shown in Klaviyo's UI for the same window.

Test 3 — Functionality (profile dump)

1. In the same terminal, change Query Level to Profile dump (entity mode).
2. Check the dimensions Profile ID, Profile email, Profile city, Profile country, Profile creation datetime.
3. Click Run Query.
4. Pass criteria: rows populate with profile attributes pulled live from https://a.klaviyo.com/api/profiles. Up to 10,000 profiles (default cap) per query.

Test 4 — Token refresh (automatic)

Klaviyo OAuth access tokens expire after 1 hour. ShopSheets refreshes them automatically using the stored refresh token before each query. To verify, wait 65+ minutes after Test 1, then re-run any query from Test 2. The query should succeed without requiring re-authorization.

Test 5 — Disconnect and data deletion

1. From the ShopSheets Dashboard, click the trash icon next to the Klaviyo connection.
2. Confirm the deletion in the dialog.
3. Pass criteria: the connection is removed from the list. The OAuth refresh token and access token are deleted from ShopSheets storage. Subsequent attempts to query Klaviyo via this connection fail until a new authorization is completed.
4. Optionally, revoke the app from your Klaviyo account at Klaviyo → Account → Settings → API Keys → Connected Apps. ShopSheets honors the revocation and the integration row is marked inactive.

Scopes used and why

• accounts:read — required by Klaviyo; used to fetch organization name to label the connection.
• campaigns:read — campaign performance and metadata.
• flows:read — flow performance and metadata.
• forms:read — form performance and metadata.
• lists:read — list metadata (id, name, created date, type).
• metrics:read — event-aggregate values (Placed Order, Active on Site, etc.).
• profiles:read — profile attributes for the Profile-dump query mode.
• segments:read — segment metadata + member counts.
• tags:read — tag names attached to campaigns and flows.

All scopes are read-only. ShopSheets does not request or use any write scopes.

Known limitations

• Profile dump is paginated at 50 profiles per page (Klaviyo API limit for sparse fieldsets including last_event_date) and capped at 10,000 profiles per query by default. For larger pulls, contact support.
• The profile_age and profile_birthday fields populate only on profiles that have $age or $birthday set in their Klaviyo properties. Otherwise they return empty.

Reviewer support

For provisioning a reviewer account, OAuth client allowlisting questions, or any test failures, contact periel@wearegrowth.co. We aim to respond within 1 business day.