Klaviyo scripts
Reference for the Klaviyo profile mapper and subscriptions provider scripts: handlers, list subscription rules, the SMS consent setting and examples.
Two scripts adjust the Klaviyo connector. The mapper changes the profile the connector sends to Klaviyo. The subscriptions provider decides which Klaviyo lists a customer is subscribed to, and for which channel. This page is the reference for extensions.klaviyo.mapper and extensions.klaviyo.subscriptions.provider. The connector is described on the Klaviyo connector pages; the rules shared by every connector script are in Connector scripts.
Registration
Key
Slot file
Methods (required in bold)
extensions.klaviyo.mapper
klaviyo.mapper.js
MapToKlaviyo
extensions.klaviyo.subscriptions.provider
klaviyo.subscriptions.provider.js
GetSubscriptions
The files live in the folder server/scripts/, with the name of the slot file. A file named /server/script/klaviyo.js is never loaded: the folder is scripts, in the plural, and the file name is the one of the slot. The slots are read and written with GET and PUT /api/{tenantId}/admin/extensions/klaviyo/scripts. When no script is registered for a key, the default behavior applies.
The slots are Profile mapper and Subscriptions provider in the Advanced tab of the Klaviyo connector.
When it runs
MapToKlaviyo runs whenever the connector builds a Klaviyo profile, right after the default mapping: in the klaviyo registration step and when a pass is installed or removed. GetSubscriptions runs in the klaviyo step of a registration flow, when the connector computes the subscription status of the customer.
The default mapping fills Email from email, LastName from lastName, FirstName from firstName, Location.Country from country, Location.City from city and Location.Zip from postCode or zipCode.
Handlers
MapToKlaviyo
account, profile
nothing
Required
Synchronous
GetSubscriptions
account
an array of { ListId?, Email?, Sms? }
Required
Synchronous
MapToKlaviyo.profileis the Klaviyo profile with the default mapping already applied. The vendor object keeps its .NET member names:PhoneNumber,ExternalId,Email,FirstName,Location, andProperties[...]for custom properties. A JSON name such asphone_numberis only the name used when the profile is sent: assigning it has no effect, which is why the example writesprofile.PhoneNumber.GetSubscriptions. It returns one entry per list:ListId(the Klaviyo list id),EmailandSmsas booleans. AListIdofnullmeans a consent update with no list. The method is synchronous: return the array, not a promise.
How the subscriptions combine with the listId setting
The subscriptions the script returns are added to the subscription of the listId configured in the connector settings. They do not replace it. To use the script alone, clear listId. The value builtin for listId updates the Klaviyo built-in consents, with no list relationship.
SMS consent
The key consents_sms controls the SMS subscription only when the connector setting Enable SMS support is on, which it is not by default. When it is off, the SMS consent is ignored and logged at debug level. A script that returns Sms: true therefore has no effect until the setting is enabled.
The values of consents_email and consents_sms may arrive as a boolean or as text, depending on the form. The connector reads them as booleans: a text value is ignored by the listId subscription. A script can convert text itself, as the example below does. The members of a returned subscription are PascalCase: ListId, Email, Sms.
Errors and edge cases
No script registered: the default mapping applies, and only the configured
listIdis used.A required method is missing: the call fails with
method <Name> missingwhen the connector reaches it.GetSubscriptionsreturns an empty array: no script subscription is added; thelistIdsubscription still applies. With nolistIdeither, no subscription update is sent. The "no list configured" warning is logged only when no script is registered.A script throws: the error is not caught and fails the
klaviyoregistration step.
Example
The subscriptions provider subscribes a customer to one list, for the channels whose consent exists on the account. The toBoolean helper converts consents_email and consents_sms because they may arrive as text.
The mapper sets the phone number of the Klaviyo profile:
Common pitfalls
The script is saved outside
server/scripts/(for example as/server/script/klaviyo.js): it is never loaded.The mapper assigns
profile.phone_number: the member isPhoneNumber.GetSubscriptionsorMapToKlaviyois declaredasync: both must be synchronous.The
listIdsetting is still set, so the customer is also subscribed to that list.SMS consent is ignored because Enable SMS support is off.
FAQ
Last updated

