> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/klaviyo.md).

# 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](https://app.gitbook.com/s/lP7d71aYydav6e0pRkxc/marketing-automation/klaviyo/reference#custom-profile-mapping); the rules shared by every connector script are in [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md).

<details>

<summary><strong>Real-world examples</strong></summary>

* A brand routes email consent to a "Newsletter" list and SMS consent to a "VIP SMS" list.
* A brand sets the phone number of the Klaviyo profile from the wallet account.

</details>

## 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

| Method             | Parameters           | Returns                                 | Required | Sync or async   |
| ------------------ | -------------------- | --------------------------------------- | -------- | --------------- |
| `MapToKlaviyo`     | `account`, `profile` | nothing                                 | Required | **Synchronous** |
| `GetSubscriptions` | `account`            | an array of `{ ListId?, Email?, Sms? }` | Required | **Synchronous** |

* **`MapToKlaviyo`.** `profile` is the Klaviyo profile with the default mapping already applied. The vendor object keeps its .NET member names: `PhoneNumber`, `ExternalId`, `Email`, `FirstName`, `Location`, and `Properties[...]` for custom properties. A JSON name such as `phone_number` is only the name used when the profile is sent: assigning it has no effect, which is why the example writes `profile.PhoneNumber`.
* **`GetSubscriptions`.** It returns one entry per list: `ListId` (the Klaviyo list id), `Email` and `Sms` as booleans. A `ListId` of `null` means 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 `listId` is used.
* **A required method is missing**: the call fails with `method <Name> missing` when the connector reaches it.
* **`GetSubscriptions` returns an empty array**: no script subscription is added; the `listId` subscription still applies. With no `listId` either, 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 `klaviyo` registration 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.

```js
const NEWSLETTER_LIST = 'WnP7MK';

function toBoolean(value) {
  return value === true || value === 'true' || value === 'y' || value === 'yes';
}

function getSubscriptions(account) {
  const subscription = { ListId: NEWSLETTER_LIST };

  if (account['email'] && account['consents_email'] !== undefined) {
    subscription.Email = toBoolean(account['consents_email']);
  }
  if (account['phoneNumber'] && account['consents_sms'] !== undefined) {
    subscription.Sms = toBoolean(account['consents_sms']);
  }

  return subscription.Email === undefined && subscription.Sms === undefined ? [] : [subscription];
}

export default function (context) {
  context.register('extensions.klaviyo.subscriptions.provider', {
    GetSubscriptions: getSubscriptions
  });
}
```

The mapper sets the phone number of the Klaviyo profile:

```js
function mapToKlaviyo(account, profile) {
  const phoneNumber = account['phoneNumber'];
  if (phoneNumber) {
    profile.PhoneNumber = phoneNumber;
  }
}

export default function (context) {
  context.register('extensions.klaviyo.mapper', {
    MapToKlaviyo: mapToKlaviyo
  });
}
```

## 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 is `PhoneNumber`.
* `GetSubscriptions` or `MapToKlaviyo` is declared `async`: both must be synchronous.
* The `listId` setting is still set, so the customer is also subscribed to that list.
* SMS consent is ignored because **Enable SMS support** is off.

## FAQ

<details>

<summary><strong>Does a script change existing profiles?</strong></summary>

Yes, once deployed: it changes how the subscription updates are computed for every profile that goes through a flow with a `klaviyo` step. Test it on a small set of test profiles first.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/scripting/extensions/klaviyo.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
