Pass your app review

Before you begin

Before you begin, confirm that your app meets Klaviyo’s app listing requirements to ensure that your submission process goes as smoothly as possible.

You will learn

This article highlights OAuth app best practices and common reasons an app fails review, helping you prepare your app for approval before submitting it to Klaviyo's integration directory. You'll learn best practices for:

• Handling your app’s OAuth flow
• Seeding profiles and events
• Naming list and profile properties
• Syncing data effectively
• Defining your event schema

You’ll also learn how to identify and avoid common app review errors, such as OAuth installation flow errors, unclear testing instructions, unused scopes, and more.

OAuth app best practices

Apply the best practices detailed below to ensure that your OAuth app is performant and offers a user experience that satisfies Klaviyo’s app listing requirements.

Handling your app’s OAuth flow

We expect that your app installations can be initiated from within your app’s platform. Additionally, when a user navigates to your app listing in Klaviyo and clicks Add app, the app installation process must be initiated on Klaviyo’s end. We require that your OAuth installation flow works on both your app's side and Klaviyo's side to ensure a seamless and consistent user experience.

When a user tries to install your app from Klaviyo, your OAuth installation flow should ensure that the user is logged in to your app's host platform before directing them to OAuth installation. Follow the installation flow below that matches your app's type.

Standalone app installation flow

If your app is a standalone app, which runs independently on its own platform, address the following scenarios in your installation flow:

Embedded app installation flow

If your app is an embedded app hosted on a different platform, such as an ecommerce platform, address the following scenarios in your installation flow:

❗️

Users installing your app from Klaviyo should not be redirected elsewhere to initiate the installation flow. Apps that only have an OAuth installation flow set up from their own platform will be rejected.

Installation errors

Your app should also handle installation errors in which a user denies permissions or leaves the installation page, resulting in an installation failure.

❗️

If a user needs to take manual, avoidable steps to install your app, it will be rejected.

Uninstallation flow

In addition to the installation flow cases, make sure that your OAuth flow handles uninstalling your app from your app’s side and from Klaviyo’s side.

Uninstalling from your app’s platform

When a user uninstalls your app from your platform, make an API call to revoke any refresh and/or access tokens for the user (https://a.klaviyo.com/oauth/revoke). After this action, the app should be removed from the account’s integration page in Klaviyo, and the user can re-install it if they wish.

📘

For a positive user experience, ensure that a disconnect option is easy to locate in your app's UI.

Uninstalling from Klaviyo

When a user uninstalls your app from Klaviyo, ensure that the status reflects properly in your app, i.e., it appears as uninstalled on your app’s platform.

Seeding profiles and events

If your app creates events or sets custom profile properties for use in flows, segments, etc. we recommend creating an example profile(s) with the properties set by your integration along with events for each of the core metrics upon installation. This enables customers to get started with your integration immediately after installation. Otherwise, they will need to wait until these properties and events propagate through naturally, which prolongs the onboarding time.

📘

App metric branding is available to all apps using OAuth. Learn how to set up branding for your app’s metrics.

Naming lists and profile properties

It’s best practice to give lists and profile properties set by your integration names that clearly identify your integration. We recommend using your app’s name or prefix, followed by a space and then the list/profile property. For example, an app named PetParty might have list properties named “PetParty Invitees” and “PetParty Attendees.”

List and profile properties should follow the same format, i.e., if an app's full name is used to describe a list property, all list and profile properties should also be described with the full name. Following a consistent naming approach will allow for your app’s properties to be easily grouped and identified in Klaviyo.

Syncing data efficiently

Respect rate limits

Your app needs to respect API rate limits to avoid unnecessary load in accordance with our API Terms of Use. Rate limits are listed in each endpoint’s API reference documentation.

Use bulk endpoints

Use our Bulk Profile Import API and Bulk Create Events API to create multiple profiles and events at a time. The Bulk Profile Import API will update matching profiles if they already exist or create them if no matching profiles are found. If you are looking to create or update a single profile, use the Create or Update Profile endpoint.

Defining event schema

It's important that you avoid making breaking changes to event payloads, as customers are relying on the payload shape to be a certain way in Klaviyo. Keep your event payloads tight and only send over data that is helpful for customers to use in Klaviyo, for example, fields that can be used in segments, flows, or message templates. Note that segmentation is only supported on top-level properties.

Common reasons an app fails review

Apps often require updates before they can be approved and published in Klaviyo’s integration directory. We’ve outlined the reasons for such updates below so that you can avoid delays in your app’s approval. Before you submit your app, make sure your app doesn’t meet any of the common reasons an app fails review.

Next steps

Now that your app meets Klaviyo’s app listing requirements and follows best practices, you can submit your app for review.

Additional resources

• Set up OAuth
• Branding for app metrics
• Create help docs for your integration