Connect Klaviyo

With the Klaviyo integration, everyone who signs up is created or updated as a profile in Klaviyo, added to the list you choose, and subscribed to email marketing.

What you need

• A Klaviyo account. The free plan works.
• A Klaviyo user who can create private API keys (in Klaviyo that is usually an Owner, Admin or Manager).

Step 1: Create a private API key in Klaviyo

1. In Scratcher, go to Settings > Integrations, click Klaviyo and look at the Setup guide: "Create a private API key. The correct permissions are pre-selected."
2. Click the link Create a private API key. Klaviyo opens with the right scopes already selected. Log in if Klaviyo asks you to.
3. Give the key a name you recognise, for example "Scratcher".
4. Check the scopes (see the list below) and click to create the key.
5. Copy the key. It starts with "pk_". Klaviyo only shows the whole key once, so keep the tab open until you have pasted it.

If you prefer to make the key yourself: in Klaviyo, open the menu under your account name, go to Settings > API keys and click Create Private API Key. Choose Custom Key and set the scopes below.

Scopes the key needs

The key needs exactly these scopes (Scratcher's help text: "The API key needs read/write access to "Lists" and "Profiles" and write access to "Subscriptions"").

• Lists: read and write. To show your lists and add people to them.
• Profiles: read and write. To create and update profiles.
• Subscriptions: write. To subscribe people to email marketing.

All other scopes can stay at No Access.

Step 2: Connect Klaviyo to Scratcher

1. In the Klaviyo dialog in Scratcher, paste the key in Private API Key. The Access permissions box lists what Scratcher can do: "Read and write access to Contacts & Lists" and "Automatic background sync for campaign participants".
2. Click Install integration. Scratcher checks that the key can read your lists.

Step 3: Turn it on in a campaign

1. In the editor, go to Connect > Integrations > Klaviyo and click Activate.
2. If you have connected more than one Klaviyo account, choose it under Select account.
3. Under External list, choose the Klaviyo list.
4. Under Field mappings, add the extra data you want on the profile. Here you type the name of the property in Klaviyo yourself (External field name), for example "favourite_product" or "Campaign".
5. Under Filter by permissions (optional), choose your marketing consent checkbox.
6. Click Save, and then Test.

Field mapping

• Email, phone number, first name and last name are sent automatically to Klaviyo's own profile fields. You don't need to map them.
• Everything you map is saved as a custom property on the profile, with the name you typed. If the property doesn't exist yet, Klaviyo creates it.
• Klaviyo only accepts phone numbers with + and country code. Make sure your form's phone field has a country code.

Consent

Scratcher subscribes everyone it sends to email marketing in Klaviyo, with "Scratcher" as the source. That's why the consent filter matters: choose your marketing checkbox under Filter by permissions (optional) if it's optional on your form.

If your Klaviyo list uses double opt-in, Klaviyo sends its own confirmation email, and people are only subscribed when they confirm. You can then start a welcome flow in Klaviyo when people are added to the list.

What is sent and when

New sign-ups are sent within a minute or two. When you activate the integration, the campaign's existing leads are sent too. When someone takes part again, their profile is updated.

Troubleshooting

Failed deliveries show under Settings > Integrations > Delivery status.

• "The API key used does not have the correct API Scopes.": the key is missing one of the scopes above. Edit the key in Klaviyo, or create a new one with the setup link and connect it with Add new account.
• "Conflict: Duplicate profile detected.": Klaviyo found two profiles that match, for example one with the email and another with the same phone number. Merge or fix the profiles in Klaviyo and resend.
• A phone number is rejected: the number has no country code. Add a country selector to the phone field on your form.
• Nothing arrives after installing: check that a list is chosen under External list in the campaign and that you clicked Save.