> For the complete documentation index, see [llms.txt](https://docs.rafflex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rafflex.io/marketing/sms-and-email/klaviyo-integration.md). # Klaviyo Integration Connect your Rafflex site to Klaviyo so opt ins, unsubscribes, orders and browsing activity flow into Klaviyo automatically, and your live competitions are available as products. *** Klaviyo is a popular email and SMS marketing platform. Rafflex links directly to your Klaviyo account, so you do not need any other tool (such as Zapier or n8n) in the middle. Once it is connected: * Customers who opt in to your marketing are added to Klaviyo as subscribed, with their name, location and mobile number when they have given them. * Customers who unsubscribe on your site are unsubscribed in Klaviyo. * Every completed order is recorded in Klaviyo as a **Placed Order**, ready for your post purchase flows and revenue reporting. * Klaviyo sees what customers browse on your site (**Viewed Product**, **Added to Cart** and **Started Checkout**), so you can build browse and basket abandonment flows. * Your live competitions can be pulled into Klaviyo as a product catalogue, for product blocks and recommendations in your emails. {% hint style="info" %} Klaviyo has told us they have some limits on who can sign up, mostly around how long a company has been trading (usually at least **18 months**). If your business is newer than that, you may need to wait or speak to their team before you can open an account. {% endhint %} Use the link below to sign up through the correct Klaviyo team. {% embed url="" %} First sign up to Klaviyo {% endembed %} *** ### Step 1: Get your Klaviyo API keys An API key is a code that lets Rafflex and Klaviyo talk to each other securely. You need two: * **Public API key.** Klaviyo creates this for you. It is a short code (Klaviyo also calls it your **Site ID**) and it is safe for it to appear on your website. * **Private API key.** You create this yourself. It must be kept secret. To find and create them: 1. Sign in to Klaviyo. 2. Open your account settings and go to **API keys** (). 3. Copy your **Public API Key / Site ID**. You do not need to create a new public key. 4. Click **Create Private API Key** and give it a name you will recognise, for example "Rafflex". 5. Choose the access level. **Full Access Key** is the simplest choice. If you prefer to give only the access Rafflex needs, choose **Custom Key** and give **Full Access** to **Events**, **Lists**, **Profiles** and **Subscriptions**. 6. Create the key and copy it straight away. Klaviyo only shows a private key in full once. {% hint style="warning" %} **Keep your private key secret.** Anyone who has it can read and change your Klaviyo data. Only paste it into your Rafflex admin panel, and never share it by email or in a screenshot. If you think it has been exposed, delete it in Klaviyo, create a new one and paste the new one into Rafflex. {% endhint %} *** ### Step 2: Add your keys to Rafflex 1. In your admin panel, click **Settings** in the left-hand menu (under **Content**), then open the **Marketing** tab. 2. Find the **Email Marketing** section at the top of the page. 3. Paste your public key into **Klaviyo Public API Key**. 4. Paste your private key into **Klaviyo Private API Key**. 5. Optionally, enter a **Klaviyo List ID** (see [Choosing a Klaviyo list](#choosing-a-klaviyo-list) below). 6. Click **Save Settings** at the bottom of the page. You will see **Marketing settings saved successfully**.
Once your keys are saved, you should see data start to arrive in your Klaviyo account as customers browse, opt in and place orders.
Each key switches on different things: | Saved key | What it switches on | | --------------------------- | --------------------------------------------------------------------------------------------------- | | **Klaviyo Public API Key** | Klaviyo's tracking on your website: **Viewed Product**, **Added to Cart** and **Started Checkout**. | | **Klaviyo Private API Key** | Sending opt ins and unsubscribes to Klaviyo. | | **Both keys** | Sending a **Placed Order** event for every completed order. | {% hint style="info" %} **Add both keys.** Orders only reach Klaviyo when the public key and the private key are both saved. {% endhint %} #### Choosing a Klaviyo list The **Klaviyo List ID** field is optional. Its note reads: "Optional: Specify the Klaviyo list ID to subscribe users to. Leave blank to use account default." * **Leave it blank** and customers who opt in are subscribed using your Klaviyo account's default settings. * **Enter a List ID** and customers who opt in are added to that list. Customers who unsubscribe on your site are unsubscribed from it too. We recommend entering a list, so all of your Rafflex subscribers land somewhere you can easily find, and so you can control how that list confirms new subscribers (see [Turning on double opt in](#turning-on-double-opt-in)). To find a List ID in Klaviyo, go to **Audience**, then **Lists & Segments**, open the list, and click **Settings**. The List ID is a short code of letters and numbers, shown on that page. *** ### Step 3: Sync your competitions with a product feed Rafflex gives you a live **product feed**: a web address that lists your competitions in a format Klaviyo understands. Adding it to Klaviyo lets you drop your competitions straight into emails as products, build product recommendations, and keep everything up to date without any manual work. Your feed address is: ``` https://yourdomain.com/api/klaviyo/products ``` Replace `yourdomain.com` with your own site domain (the address customers visit to enter your competitions). #### What the feed includes For every competition in the feed, Klaviyo receives: * Competition title and description * A link to the competition page on your site * The featured image (if a competition has no featured image, a placeholder image is used instead, so it is worth adding one) * Price, and sale price if one is set * Cash alternative * Closing date and draw date * Total number of tickets, tickets remaining and percentage sold * Game type, and whether the competition is featured #### Which competitions appear The feed only lists competitions customers can enter right now. A competition is left out if it is: * switched off (not **Active**), * [scheduled](/create-your-first-raffle/create-a-competition/schedule-a-competition.md) and not yet open (it is added once its start date arrives), * sold out or past its closing date, or * a [hidden VIP competition](/create-your-first-raffle/hidden-vip-competitions.md). The feed keeps itself up to date as you launch and close competitions. When you save a change to a competition, the feed is refreshed straight away. Changes that happen on their own, such as a scheduled competition opening, a competition reaching its closing date or tickets selling, can take up to an hour to show in the feed. Klaviyo then refreshes its copy on its own schedule. #### How to add the feed to Klaviyo 1. In Klaviyo, go to **Content**, then **Products**. 2. In the top right, click **Manage Custom Catalog Sources**. 3. Click **Add new source**. 4. Give the source a name (for example "Rafflex Competitions") and paste in your feed address from above. 5. Click **Define Source**. 6. On the mapping screen, Klaviyo lines up the feed fields for you automatically. Check that **Item ID**, **Title**, **URL**, **Image URL** and **Description** are all matched, adjust anything that looks off, then finish setup. {% hint style="info" %} Klaviyo only needs you to confirm five core fields (ID, title, link, image and description). Rafflex already provides these, along with the extra details listed above, so the mapping step is usually just a quick check. {% endhint %} Once the source is connected, you can use Klaviyo's product blocks and recommendations to feature your competitions in any email. *** ### What Rafflex sends to Klaviyo | When this happens | Rafflex tells Klaviyo | | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A customer opts in at checkout, when registering, or through a newsletter sign up box | Create or update their profile and set email marketing to **Subscribed**. If they have given a mobile number Rafflex can recognise, SMS marketing is set to **Subscribed** too. | | A customer unsubscribes in their account | Set email marketing (and SMS, if they have a mobile number) to **Unsubscribed**. | | You click **Unsubscribe Email Marketing** on a customer, or lock their account | Set email marketing (and SMS, if they have a mobile number) to **Unsubscribed**. | | A customer takes a timeout from their account | Set email marketing (and SMS, if they have a mobile number) to **Unsubscribed**. | | A customer account is deleted (by you, or by the customer) | Set email marketing to **Unsubscribed**. Their SMS subscription is not changed, so if they were subscribed to SMS, unsubscribe their mobile number in Klaviyo yourself. | | An order is completed | Record a **Placed Order** event. This includes £0 orders (for example when a discount covers the full price) and orders paid with site credit, as well as card and PayPal orders. | | A customer views a competition | Record a **Viewed Product** event. | | A customer adds tickets to their basket | Record an **Added to Cart** event. | | A customer opens the checkout page | Record a **Started Checkout** event. | #### Profile details When a customer opts in, their Klaviyo profile is filled in with their email address and, when they have given them, their first name, last name, town, county, country, postcode and mobile number. Customers who are logged in are also recognised by email address while they browse, so their **Viewed Product**, **Added to Cart** and **Started Checkout** activity is linked to the right profile. #### Placed Order details Each **Placed Order** event includes the order total, the competitions bought (with names, quantities, prices, images, links and [categories](/create-your-first-raffle/product-categories.md)), any discount code used, and any site credit used. You can use these in Klaviyo flows and segments, for example to thank first time customers or to target people who bought in a particular category. *** ### How marketing consent works with Klaviyo Customers opt in to your marketing in a few places on your site: * **At checkout**, with the box labelled **Receive Discount Codes & Latest Competitions**. * **When they create an account**, with the box labelled **Receive discount codes & latest competitions**. This box starts unticked. * **In a newsletter sign up box**, such as the **Join the list** box in your footer or a **Newsletter** block on one of your pages. #### Turning on double opt in Klaviyo can ask every new subscriber to confirm by email before they receive any marketing. This is called **double opt in**. Klaviyo then keeps its own record of that confirmation, including the date and time. To switch it on, go to **Audience**, then **Lists & Segments** in Klaviyo, open the list your customers are added to (the one in your **Klaviyo List ID** field), and choose **Settings**, then **Opt-in Process**. Select **Double opt-in** and save. {% hint style="success" %} We recommend double opt in. It gives you a clear, timestamped record of consent held by Klaviyo, and it means a customer only ever receives marketing after they have confirmed they want it. It works best when you have entered a **Klaviyo List ID** in Rafflex, so you know exactly which list's settings apply. {% endhint %} *** ### Customers who opted in before you connected Klaviyo Rafflex sends opt ins from the moment your private key is saved. Customers who opted in earlier are not copied across automatically. Please do not upload the customer export from your admin panel into Klaviyo as a subscribed list. That export includes **every** registered customer, not only those who agreed to marketing. See [Marketing Consent and Unsubscribes](/marketing/sms-and-email/marketing-consent-and-unsubscribes.md#importing-customers-into-a-marketing-tool). If you would like help bringing your existing customers across, contact Rafflex support. Before you ask, be aware of how this works: * It copies **every customer who has not unsubscribed** on your site. That can include people who never ticked a marketing box. * They are added to Klaviyo as subscribed to email, without a double opt in confirmation. * You need a **Klaviyo List ID** saved first. Only ask for this if you are confident that you have consent to email those customers. *** ### Order confirmation emails Order confirmations, and other emails about a customer's account or purchases, are sent by your site automatically, whether or not the customer has opted in to marketing. Marketing consent only ever affects marketing. You do not need to build order confirmation emails in Klaviyo. If you do send your own post purchase emails from Klaviyo using the **Placed Order** event, make sure they do not duplicate the confirmation your site already sends. *** ### Troubleshooting
Customers are not appearing in Klaviyo when they opt in * Check that **Klaviyo Private API Key** is filled in and that you clicked **Save Settings**. * Make sure you pasted the **private** key into the private field, and the **public** key into the public field. They are easy to swap. * If you chose **Custom Key** in Klaviyo, check that it has full access to **Events**, **Lists**, **Profiles** and **Subscriptions**. * If you entered a **Klaviyo List ID**, check it matches a list that exists in your Klaviyo account. * If double opt in is switched on, the customer appears in Klaviyo but is only subscribed after they confirm by email.
Orders are not showing as Placed Order events Placed Order events are only sent when **both** keys are saved. Check that **Klaviyo Public API Key** and **Klaviyo Private API Key** are both filled in. Only completed orders are sent, so a checkout the customer did not finish will not appear.
Viewed Product, Added to Cart or Started Checkout are missing These come from Klaviyo's tracking on your website and need the **Klaviyo Public API Key**. Some customers use browser settings or ad blockers that stop tracking, so you may not see every visit. For anonymous visitors, Klaviyo can only link activity to a profile once it knows who they are, for example after they log in or click a link in one of your Klaviyo emails.
A competition is missing from my Klaviyo products Check it is live: **Active**, past its start date, not sold out, not closed and not a **Hidden / VIP Competition**. Then allow up to an hour for the feed to update, plus however long Klaviyo takes to refresh your catalogue.