Klaviyo connector

The Klaviyo connector links one Klaviyo account to an Orishare environment. Orishare keeps the loyalty properties of each customer's Klaviyo profile current and sends loyalty activity as Klaviyo events, so you can build segments and flows ("you are 50 points from Gold", "your birthday reward is waiting") in Klaviyo. The sync is outbound only: Orishare never reads your Klaviyo data and never sends a message itself.

1. Install the connector

Create a private API key in Klaviyo (Settings, API keys) with full access to Profiles and Events. The key is write-only: Orishare stores it encrypted and no response, list or audit record ever returns it.

curl -X POST "$ORISHARE_API/v1/connectors" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: klaviyo-connector" -H "Content-Type: application/json" \
  -d '{"provider":"klaviyo","external_account":"AbC123",
       "credentials":{"api_key":"pk_..."},
       "config":{"klaviyo":{"email_attribute":"email","currencies":["points","credit"],
                            "tier_programs":["VIP Club"]}}}'

• external_account is your Klaviyo public API key (the six character site id).
• config.klaviyo.email_attribute names the customer attribute that holds the email address (default email). Profiles are identified by that email, and your Orishare external_id is sent as the Klaviyo external_id. Customers without a valid email are skipped and counted.
• config.klaviyo.currencies limits which currencies (by code) are synced, and tier_programs which tier programs (by id or name). Both default to all.
• Klaviyo sends Orishare no webhooks, so no webhook_secret is needed.

2. What appears in Klaviyo

Profile properties, per synced currency and tier program (the currency code and the program name are written in lower snake case):

Events (Klaviyo metrics), each with a stable unique_id so a resend is never counted twice:

Manual balance adjustments update the profile properties but are not sent as events.

3. How the sync runs

A scheduled pass runs every five minutes. It pushes only the customers whose loyalty state changed since their last push (bulk profile import, in batches of up to 500), and forwards the events recorded since the last pass. Events reach Klaviyo five to ten minutes after they happen. Nothing is sent before the connector is installed: the first pass pushes every customer's current state once.

• When Klaviyo asks Orishare to slow down (HTTP 429), the next attempt waits for the time Klaviyo names. When Klaviyo is unavailable (5xx), attempts back off from one minute up to one hour. Nothing is lost while waiting.
• When Klaviyo rejects the key (401 or 403), the connector is disabled and GET /v1/connectors/{id} shows why in disabled_reason. Send a new key to reactivate it:

curl -X PATCH "$ORISHARE_API/v1/connectors/$CONNECTOR_ID" -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"active","credentials":{"api_key":"pk_..."}}'

4. Status and full resync

curl "$ORISHARE_API/v1/connectors/$CONNECTOR_ID/klaviyo/status" -H "Authorization: Bearer $SECRET_KEY"

{
  "synced": 1200,
  "pending": 3,
  "skipped_no_email": 40,
  "failed": 0,
  "resync_pending": false,
  "last_run_at": "2026-10-04T12:05:00.000Z",
  "last_success_at": "2026-10-04T12:05:00.000Z",
  "next_attempt_at": null,
  "last_error": null,
  "disabled_reason": null
}

To push every profile again (for example after deleting properties in Klaviyo), queue a full resync. Asking again while one is pending changes nothing.

curl -X POST "$ORISHARE_API/v1/connectors/$CONNECTOR_ID/klaviyo/resync" \
  -H "Authorization: Bearer $SECRET_KEY" -H "Idempotency-Key: klaviyo-resync-1"

5. Data sent to Klaviyo

Only what is listed above: the email address, your external id, the loyalty properties and the loyalty events. No other customer attribute leaves Orishare. Removing a birthday or a referral code in Orishare does not delete the property already in Klaviyo.