Add a custom action to a flow

🚧

Adding a custom action to a flow is a gated feature. To have access, you must have at least 400,000 active profiles in Klaviyo.

You will learn

Learn how to add a custom action to a flow in Klaviyo that executes custom Python or Node.js code. Custom actions allow you to move data and build a personalized experience for your business.

Before you begin

Custom actions require custom development and experience with either Python or Node.js. Klaviyo’s support team is unable to offer hands-on assistance. If you are not a developer, consider reaching out to a Klaviyo Partner for assistance.

Custom action use cases

Example use cases for custom actions include:

• Normalizing Placed Order values across storefronts that use different currencies.
• Mark coupons as used once they are redeemed in an order.
• Get weather information to use in personalizing content based on users location.
• Modifying an event payload and forwarding to an external webhook endpoint.
• Saving parts of an event payload as customer profile properties.
• Using GPT-3 to generate personalized text that thanks a customer for their order.
• Setting a customer's birthdate on their profile after they sign up.
• Sending a Slack or Microsoft Teams notification in response to a given event.

Add a custom action to your flow

1. Navigate to a specific flow.
2. In the flow builder, drag and drop a Custom Action into the flow.

3. In the sidebar that appears, select either Python or Node.js.

4. Click on a prebuilt action or a blank Python or Node.js action.

📘

If you need help designing an action from scratch, view a prebuilt action as an example. Each example includes a Readme section explaining the action.

5. In the modal showing the preview, click Select. After selecting an action, you will be brought to an interface with the following tabs:
   • Editor
   • Test output
   • Logs
   • Needs review
     
     

Read the sections below for information on each tab.

Granting permissions to custom actions

The first time you create a new code function you will be asked to authenticate the Code OAuth application. This will allow the code functions you write to access data in your Klaviyo account on your behalf. Once you’ve granted Code access, you will be brought to the Code editor.

Editor

The Editor tab contains 3 sub-tabs:

• Code
  The code tab has an editor where you can write Python or Javascript code.
• Modules
  Modules are 3rd party packages that add functionality to your functions.
• Environment Variables
  Environment variables are the key-value pairs that your function accesses when it runs.

Code

On the Code tab, you’ll see an editor you can use to write Python or Node.js functions that are executed in response to the selected topic.

Writing function code

In order for Klaviyo to execute the code you write, you need to wrap it in a function named handler that accepts 3 parameters:

• event
  Consists of the event data associated with the triggering event in JSON:API format. If the trigger is non-event based (e.g., Added To List), then the value of this parameter will be None or null depending on the language.
• profile
  The JSON:API profile object associated with the current evaluation. The schema of the profile object matches the profile object returned by the Klaviyo API.
• context
  Contains additional metadata about the function execution

🚧

In Python, defining the handler is all that’s needed, but with Node.js, you must also export the function so that Klaviyo can access it. In Node.js, it’s good practice to declare your handler function as async, so that you can await Promises inside it.

The klaviyo module

All Code functions come with a custom klaviyo package pre-installed into your Code environment. The klaviyo module allows your functions to access the data in your Klaviyo account without needing to supply any credentials, such as an API key.

The API of the klaviyo module depends on whether your code is written in Python or Javascript.

Python klaviyo module

The API of the klaviyo module is the same as the klaviyo SDK object you would normally instantiate yourself using the klaviyo-api Python module. You can think of the klaviyo module as a pre-instantiated klaviyo SDK client.

For instance, in a traditional workflow you would first instantiate a new Klaviyo SDK client by passing an API key to the constructor, and then use the resulting SDK object.

from klaviyo_api import KlaviyoAPI
import os
def handler(event, profile, context):
  klaviyo = KlaviyoAPI(api_key=os.getenv("KLAVIYO_API_KEY"))
  print(klaviyo.Metrics.get_metrics())

With Code, you just need to import the klaviyo object and authentication is handled for you.

import klaviyo

def handler(event, profile, context):
  print(klaviyo.Metrics.get_metrics())

Available API objects and their methods can be found at https://pypi.org/project/klaviyo-api.

Javascript klaviyo module

When using the built-in klaviyo module from your Javascript functions, just import the specific Klaviyo features you want to access using curly brace syntax from the klaviyo module. Then use them as you normally would an API object using the klaviyo-api JS module.

import { Metrics } from 'klaviyo';
export default async (event, profile, context) => {
  console.log(await Metrics.getMetrics())
}

Available API objects and their methods can be found at https://www.npmjs.com/package/klaviyo-api.

External modules

On the Modules tab, you can select from the most popular prebuilt modules (i.e., 3rd-party packages that add capabilities to your functions).

To add an external module to use in your code:

1. Click Add module.

2. On the modal that appears, search and select the module you’d like to add:

Once added, you can use the module with the code you write in Klaviyo.

📘

Refer to the external module’s native documentation for information regarding how to use it.

Environment variables

The Environment variables tab allows you to set key-value pairs that your code in Klaviyo can reference when it runs. These can be used to store information like credentials and secret keys so your functions can access them as they run.

To add an environment variable:

1. Click Add a variable.

2. On the modal that appears, you can set a key-value pair for your environment variable.

Once created, the environment variables will be listed on the page and can be used in your code.

📘

To access your environment variables in your code, use os.getenv("Key") for Python, or process.env.Keyfor Node.js.

Test output

The Test output tab allows you to test your code with recent events to confirm that the output is behaving as expected.

To test your function:

1. Click Run Test.

2. On the modal that appears, select a profile or event to test with. You can select profiles from the 10 most recent events captured in Klaviyo.

After selecting an event to test with, the test output will be shown.

Logs

The Logs tab shows the health of the currently viewed action. You’ll see:

• Profile
  The email address of the profile associated with the given function execution. Click the email to navigate to the profile page.

• Status
  The progress of a function’s execution.

• Run ID
  The unique ID of this function execution. Click the ID to open a side drawer with
  additional execution information, such as the function logs.

• Response time
  The amount of time it takes for your code to execute in response to an event.

• Date
  A timestamp of when the function was executed.

Needs review

If the custom action is set to manual status, profiles will be queued in the Needs Review tab to be manually approved for the code to execute.

Deploy the action and set it live

1. In the code editor, click Deploy in the upper right to deploy your local code changes. Any changes will be preserved even if you leave the page, but only deployed changes will be reflected in subsequent flow evaluations. If you chose a prebuilt function and didn’t make any changes, it will automatically be deployed.

2. Click Done in the upper right.
3. Click on the custom action again in the flow builder.
4. In the sidebar, rename the action if desired.
5. Click the Status dropdown to change the status from Draft to Manual or Live.

6. Click Save.

Limits

Limits

Function timeout: 10 seconds
Action rate limit: 10 evaluations per second

Additional resources

• How to add a webhook action to a flow.
• How to add an update profile property action to a flow
• How to add a internal alert action to a flow