> 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.md).

# Connector scripts

Every extensions.\* script endpoint by connector, its slot file, required methods, and the rules that apply to all connector scripts.

Connector scripts adjust what a ready-made connector of The Wallet Crew already does: they add fields to the default mapping between a vendor record and the account, choose a pass type, filter a list, rename an event or rewrite a request. They never replace the connector itself. This page lists every connector endpoint (`extensions.*` keys), explains the rules they share, and links to one page per connector.

A connector script is not the right tool when no connector is involved: a pass enriched from a brand's own API uses a [pass data provider](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/pass-data-provider.md), and a registration pushed to a custom system uses a [customer pipeline element](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/customer-pipeline-element.md).

## How connector scripts work

A connector script is an ordinary tenant script: a `.js` file under `server/scripts/` in the advanced configuration, loaded with every other file, whose default export registers one key. Everything described in [How scripts run](https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md) and [Handlers](https://docs.thewalletcrew.io/developers-guides/scripting/handlers.md) applies. What differs from the `runtime.*` endpoints is who calls the script: the connector calls it at a fixed point of its own work, usually right after its default mapping, and only while the connector is configured for the tenant. A script registered for a connector that the tenant does not use is never called.

The connector hands the script live objects and keeps going with whatever the script leaves in them. A mapper therefore changes its arguments in place and returns nothing; the few methods that return a value (a pass type, a filter decision, a patch, an event) are listed as such on each connector page.

### Script slots and file names

Most connectors expose their scripts as **script slots** in their settings screen in the admin console (the **Advanced** tab). A slot edits one file whose name is fixed: the registration key without its leading `extensions.`, under `server/scripts/`, with the `.js` extension. The key `extensions.comarch.couponMapper` lives in `server/scripts/comarch.couponMapper.js`. A slot with no file shows a starter script that registers nothing until its registration lines are uncommented.

Nothing prevents another file from registering the same key, but only one registration wins (the last one loaded, and the load order across files is not defined). The slot editor lists those other files as conflicts so that they can be removed: each key belongs in exactly one file, and for a connector key that file should be the slot file.

Saving a slot writes the file only. It does not run it, so a syntax error appears when the scripts next load, and then makes every script of the tenant fail, not only the connector's. Saving the whole advanced configuration does run the loader and reports such an error at save time. Slot contents are trimmed, an empty content is refused, and clearing a slot deletes its file.

The same slots can be read and written through the API, one endpoint per connector, with that connector's settings scope (for example `tenant.secutix.settings:read` and `:write`); see the [Advanced section of the API reference](https://docs.thewalletcrew.io/api-reference/).

### Required and optional methods

Each method of a connector endpoint is either optional or required, and the difference only shows at run time. An optional method that the script leaves out behaves as if it returned nothing (`null`, `false` or no change), so the default behavior applies. A required method that is left out fails with the error `method <Name> missing` at the moment the connector reaches it, which usually means at the next pass refresh or registration, not at save time. The tables on the connector pages mark every method; when an endpoint has two required methods, a script that only needs one direction still registers the other as an empty function.

Method names are matched exactly and are case-sensitive: `MapFromY2`, not `mapFromY2`. A common pattern names the JavaScript function in camelCase and registers it under the PascalCase key, as in `{ MapFromY2: mapFromY2 }`.

### Member names inside connector objects

Vendor objects keep the member names of their .NET type. Most are PascalCase (`data.EmailData.Email`, `coupon.CouponNumber`, `customer.Properties`), a few generated from the vendor's own contract are camelCase (Cegid UR: `data.person.firstName`), and a type declared with an explicit JavaScript name uses that name (Comarch `status.activeRegistrationCount`). The editor typings show the exact names. An object a script returns follows the same rule: `{ Url, Headers, Content }` for a connection interceptor, `{ Name, Properties }` for a Bloomreach event. A misspelled member is not an error: it is ignored and the member keeps its default. The account itself is a flat dictionary with the usual keys, described in [Data objects](https://docs.thewalletcrew.io/developers-guides/scripting/data-objects.md). Enumerations arrive as numbers: `device` is `0` for Apple and `2` for Google.

### Connection interceptors

Cegid Y2 and Cegid UR expose a connection interceptor that sees every SOAP call the connector makes. `OnBeforeRequest(url, headers, content)` must return `{ Url, Headers, Content }`, and the connector **replaces the URL and all request headers** with what it returns: a header left out is removed. The reliable pattern copies the headers it receives, changes what it needs and returns the full set, including `SOAPAction`. `OnAfterRequest(soapAction, content)` must return the response body as a string. Both methods are required and asynchronous: each must return a promise, so declare them `async`. An interceptor runs on every call, so anything slow in it slows the whole connector.

## Endpoints by connector

| Connector                                                                                        | Key                                                    | Methods (required in **bold**)                       | Slot file                                      |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------- |
| [Actito](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/actito.md)         | `extensions.actito.profile.mapper`                     | **`MapFromActitoProfiles`**                          | `actito.profile.mapper.js`                     |
| [Aparté](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/aparte.md)         | `extensions.aparte.ticket.mapper`                      | `MapFromAparte`, `GetPassType`                       | `aparte.ticket.mapper.js`                      |
| [Bloomreach](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/bloomreach.md) | `extensions.bloomreach.contact.finder`                 | **`GetContactIdentifiers`**                          | `bloomreach.contact.finder.js`                 |
|                                                                                                  | `extensions.bloomreach.customer.mapper`                | `MapToBloomreach`, `MapFromBloomreach`               | `bloomreach.customer.mapper.js`                |
|                                                                                                  | `extensions.bloomreach.event.interceptor`              | **`Intercept`**                                      | `bloomreach.event.interceptor.js`              |
| [Cegid Y2](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/cegid-y2.md)     | `extensions.cegid.y2.mapper`                           | **`MapFromY2`**, **`MapToY2`**                       | `cegid.y2.mapper.js`                           |
|                                                                                                  | `extensions.cegid.y2.advisorRepository`                | **`Filter`**, `Project`                              | `cegid.y2.advisorRepository.js`                |
|                                                                                                  | `extensions.cegid.y2.connectionInterceptor`            | **`OnBeforeRequest`**, **`OnAfterRequest`**          | `cegid.y2.connectionInterceptor.js`            |
| [Cegid UR](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/cegid-ur.md)     | `extensions.cegid.ur.mapper`                           | `MapFromUR`, `MapToUR`                               | no slot                                        |
|                                                                                                  | `extensions.cegid.ur.connectionInterceptor`            | **`OnBeforeRequest`**, **`OnAfterRequest`**          | no slot                                        |
| [Comarch](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/comarch.md)       | `extensions.comarch.customerMapper`                    | `MapFromComarch`, `MapTransactionBalanceFromComarch` | `comarch.customerMapper.js`                    |
|                                                                                                  | `extensions.comarch.locationMapper`                    | `MapFromComarch`                                     | `comarch.locationMapper.js`                    |
|                                                                                                  | `extensions.comarch.walletInstallationCustomerUpdater` | `Update`                                             | `comarch.walletInstallationCustomerUpdater.js` |
|                                                                                                  | `extensions.comarch.couponMapper`                      | **`MapFromComarch`**                                 | `comarch.couponMapper.js`                      |
| [Klaviyo](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/klaviyo.md)       | `extensions.klaviyo.mapper`                            | **`MapToKlaviyo`**                                   | `klaviyo.mapper.js`                            |
|                                                                                                  | `extensions.klaviyo.subscriptions.provider`            | **`GetSubscriptions`**                               | `klaviyo.subscriptions.provider.js`            |
| [Secutix](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/secutix.md)       | `extensions.secutix.contact.mapper`                    | `MapToSecutix`, `MapToNeostore`                      | `secutix.contact.mapper.js`                    |
|                                                                                                  | `extensions.secutix.contact.passUpdater`               | **`OnPassInstallationStatusChanged`**                | `secutix.contact.passUpdater.js`               |
|                                                                                                  | `extensions.secutix.movement.mapper`                   | **`MapFromSecutix`**                                 | `secutix.movement.mapper.js`                   |
|                                                                                                  | `extensions.secutix.ticket.passTypeFinder`             | **`GetPassType`**                                    | `secutix.ticket.passTypeFinder.js`             |
| [Shopify](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/shopify.md)       | `extensions.shopify.customerMapper`                    | `MapFromShopify`, `MapToShopify`                     | `shopify.customerMapper.js`                    |

`MapToNeostore` in the Secutix contact mapper is a legacy handler name: the prefix `neostore` is the platform's former name and is kept in technical identifiers (see [Obsolete neostore names](https://docs.thewalletcrew.io/developers-guides/scripting/modules/obsolete-neo-names.md)).

A method that returns a value or nothing is synchronous: an `async` handler is not awaited, so changes made after an `await` are lost. Only `GetContactIdentifiers` (Bloomreach), `GetPassType` (Aparté, Secutix) and the connection interceptors (`OnBeforeRequest`, `OnAfterRequest`) are asynchronous, and they must return a promise. Each connector page states it per method; the platform-wide list is in [Handlers](https://docs.thewalletcrew.io/developers-guides/scripting/handlers.md#synchronous-and-asynchronous-handlers).

The Cegid UR endpoints have no slot: their scripts are written as any file under `server/scripts/` in the advanced configuration. The Cegid Y2 connection interceptor has a slot file in the API but no tab in the settings screen, so it is edited in the advanced configuration as well.

Each connector page links to the connector's own setup documentation in the Connectors section; scripts only make sense once that setup works without them.

## What scripts typically add

The same few shapes cover most connector scripts seen in production. A **mapper** copies one or two vendor fields that the default mapping ignores onto the account (a tier, a store, a custom attribute), or writes an account field the default mapping does not send (a consent, a user field). A **pass type choice** returns a pass type name for a ticket or a coupon and `null` everywhere else, so the connector's default resolution still applies. An **install-state hook** writes "installed" or "uninstalled" into a CRM field when a pass is added to or removed from a wallet. A **filter or interceptor** drops or renames what the connector would otherwise send.

Connector scripts run inside the request or job that triggered them, often on every pass refresh, so they stay short. A mapper that calls an external service with [`fetch`](https://docs.thewalletcrew.io/developers-guides/scripting/globals/fetch.md) multiplies that call by every refresh: such a call uses `Cache`, and where it is not essential, it fails softly instead of throwing.

## Errors and edge cases

* **No script registered**: the connector applies its default behavior and nothing is logged as an error.
* **Required method missing** (in the registered object): `method <Name> missing` when the connector reaches it; the operation that called the script fails.
* **Handler throws**: the error propagates to the connector operation that called it (a pass refresh, a registration step, an event sent to a vendor), except where a connector page states that the error is logged and ignored.
* **Several files register the key**: one wins, unpredictably. The slot editor lists the other files.
* **A syntax error in any script file**: every script endpoint of the tenant fails, connector or not.
* **Wrong member casing in a returned object**: the member is silently ignored.

## Checking the result

The quickest check is the slot editor: it shows the file content, the exact key, and any conflicting file. A mapper is then checked by refreshing a test pass and reading the account fields it should have written in the pass preview or the template variables; a write-direction mapper is checked in the vendor's own admin screens after a test registration. When nothing changes, the usual causes are, in order: the registration lines of the starter script are still commented out, the method name differs in case, a second file registers the same key, or the connector never reaches the script because the setting or identifier it depends on is missing (each connector page lists these). Script logs are described in [Utility globals](https://docs.thewalletcrew.io/developers-guides/scripting/globals/tools.md#console); see also [Troubleshooting](https://docs.thewalletcrew.io/developers-guides/scripting/troubleshooting.md).

## FAQ

<details>

<summary><strong>Can a connector script live in a file other than its slot file?</strong></summary>

Yes, the loader reads every file under `server/scripts/`, and the key is what matters. The slot editor will then show the slot as empty and list the other file as a conflict. Keeping each connector key in its slot file avoids that confusion and lets the settings screen show the real script.

</details>

<details>

<summary><strong>Can one file register endpoints of several connectors?</strong></summary>

Yes. It defeats the slot editor, though, which expects one key per slot file, and it makes one syntax error break several integrations at once. One key per file is the recommended layout.

</details>

<details>

<summary><strong>Can a connector script call the platform's own API to change a pass?</strong></summary>

It should not. A mapper changes the objects it receives, and the connector saves them; calling the platform's REST API from inside a connector step creates loops and races with the operation already in progress.

</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.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.
