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

# Scripting

What tenant scripts can do on The Wallet Crew, which endpoint or connector extension fits a need, the mental model behind every script and a build checklist.

Scripts let a brand plug its own logic into The Wallet Crew without a custom deployment: a few lines of JavaScript can fetch a loyalty balance from a CRM, choose which pass type a new customer gets, notify a warehouse when a pass is installed, or decide which email template an enrolment confirmation uses. The platform stays in charge of the flow (enrolment, pass creation, scheduling, sending); the script only answers the specific question the platform asks at a specific moment.

A script is useful only when the platform has an extension point for the need. The list of extension points is closed: each one has an exact registration key, exact handler names and an exact return shape, all documented in [Runtime endpoints](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints.md) and, for connector-specific mapping, [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md). When a need is not on those lists, a script cannot cover it, and the request goes to The Wallet Crew support.

<details>

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

* A retail brand reads the loyalty balance and tier of each member from its CRM every time a pass is rendered, with a short cache, so the pass always shows a recent value.
* A ticketing brand chooses between a "season ticket" and a "single event" pass type when a pass is created, based on a product code carried by the identifiers.
* A brand mirrors the wallet installation status of each customer ("Installed" / "Uninstalled") into a user field of its marketing platform.
* A brand with its own transactional email provider routes every platform email through a script that calls that provider.
* A brand builds the list of passes to update each night from a data warehouse query, with a notification text for the passes that changed tier.

</details>

## I want to…

| I want to…                                                                          | Use                                               | Page                                                                                                                                              |
| ----------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Show data from an external system (CRM, ERP, ticketing) on a pass                   | Pass data provider (`Fill`)                       | [Pass data provider](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/pass-data-provider.md)                                   |
| Move an older `customerProvider` script to the current model                        | Obsolete customer provider                        | [Obsolete customerProvider script key](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/customer-provider-obsolete.md)         |
| Push a new registration to an external system when a customer enrols                | Pipeline element in a flow (`CreateOrUpdate`)     | [Customer pipeline element](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/customer-pipeline-element.md)                     |
| Choose the pass type, or change the identifiers, while a pass is created or updated | Pass updater (`OnPassCreating`, `OnPassUpdating`) | [Pass updater](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/pass-updater.md)                                               |
| React when a pass is created, updated, installed or uninstalled                     | Pass updater (notification hooks)                 | [Pass updater](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/pass-updater.md)                                               |
| Update many passes on a schedule from a query run by a script                       | Scripted push updates (`GetPasses`)               | [Push updates](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/push-updates.md)                                               |
| Transform the rows of a bulk pass-update file before they are applied               | Row transformer                                   | [Bulk pass update row transformation](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/bulk-pass-update-row-transformation.md) |
| Send the platform's transactional emails through another provider                   | Email engine (`SendEmail`)                        | [Email engine](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/email-engine.md)                                               |
| Choose, or skip, the enrolment confirmation email                                   | Email challenge template finder                   | [Email challenge template](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/email-challenge-template.md)                       |
| Refuse an enrolment that does not satisfy a business rule                           | Account validator (`Validate`)                    | [Account validator](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/account-validator.md)                                     |
| Change the tracking parameters added to links                                       | Link URL enrichment                               | [Link URL enrichment](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/link-url-enrichment.md)                                 |
| Compute the benefits attached to a pass                                             | Benefit provider                                  | [Benefit provider](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/benefit-provider.md)                                       |
| Generate the codes of a benefit template                                            | Benefit code generator                            | [Benefit code generator](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/benefit-code-generator.md)                           |
| Recover an Apple pass the platform no longer knows                                  | Apple pass resolver                               | [Apple pass resolver](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/apple-pass-resolver.md)                                 |
| Adjust how a connector maps its data (Cegid, Secutix, Bloomreach, …)                | Connector extension scripts                       | [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md)                                                      |
| Call an HTTP API from a script                                                      | `fetch`                                           | [fetch](https://docs.thewalletcrew.io/developers-guides/scripting/globals/fetch.md)                                                               |
| Read an API key or password from a script                                           | `twc/secrets`                                     | [twc/secrets](https://docs.thewalletcrew.io/developers-guides/scripting/modules/secrets.md)                                                       |
| Parse dates, normalize text, sign a webhook                                         | Globals                                           | [Utility globals](https://docs.thewalletcrew.io/developers-guides/scripting/globals/tools.md)                                                     |
| See every endpoint at a glance                                                      | Endpoint index                                    | [Runtime endpoints](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints.md)                                                       |

## The mental model

Every script follows the same five steps. Understanding them removes most of the surprises, because almost every scripting problem is a failure at one of the five. A pass type is shown as a pass template in the admin console; the scripting pages say pass type, as the configuration files do.

1. **Files.** A script is a JavaScript file stored under `server/scripts/` in the tenant's advanced configuration, in the admin console under **Settings → Advanced → Advanced configuration**. Every file in that folder, subfolders included, whose name ends in `.js` is a script. Scripts are part of the configuration: they are versioned and saved together with the other configuration files.
2. **Loading.** Each platform component loads every script file the first time it needs one; a saved change applies from the next request or job ([How scripts run](https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md#when-files-are-loaded)).
3. **Registration.** Each file exports a default function that receives a `context` and calls `context.register(key, handlers)`. The key names the extension point (for example `runtime.scriptable.passDataProvider.memberLookup`) and `handlers` is an object whose properties are the functions the platform may call.
4. **Calling.** When the platform reaches an extension point, it looks the key up and calls the handler by its exact, case-sensitive name (`Fill`, `OnPassCreating`, `GetPasses`, …) with the documented arguments. Some extension points also need a line of configuration that points at the script, such as `scriptId` in a pass type or a flow.
5. **Returning.** The handler returns a value, which the platform converts by member name; [Handlers](https://docs.thewalletcrew.io/developers-guides/scripting/handlers.md) tabulates what a missing, empty or failing handler does.

The time limits are stated in [How scripts run](https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md#time-limits).

## Where to start

A first working script takes a few minutes: [First script](https://docs.thewalletcrew.io/developers-guides/scripting/first-script.md) creates a pass data provider end to end, wires it into a pass type and verifies the result. The other pages of this section then cover the topics in the order they usually come up.

| Page                                                                                                                                                                | Read it to…                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [First script](https://docs.thewalletcrew.io/developers-guides/scripting/first-script.md)                                                                           | Build and verify a working pass data provider                                                   |
| [How scripts run](https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md)                                                                     | Understand loading, registration, validation at save and the effect of an error                 |
| [Handlers](https://docs.thewalletcrew.io/developers-guides/scripting/handlers.md)                                                                                   | Know how handler names, return values and failures are handled, with a table for every endpoint |
| [Data objects](https://docs.thewalletcrew.io/developers-guides/scripting/data-objects.md)                                                                           | Read and write the entity, identifiers, dates, numbers and enums correctly                      |
| [Recipes](https://docs.thewalletcrew.io/developers-guides/scripting/recipes.md)                                                                                     | Start from a tested pattern for a common need                                                   |
| [Troubleshooting](https://docs.thewalletcrew.io/developers-guides/scripting/troubleshooting.md)                                                                     | Go from a symptom to its cause                                                                  |
| [Best practices](https://docs.thewalletcrew.io/developers-guides/scripting/best-practices.md)                                                                       | Review a script before it goes to production                                                    |
| [Globals](https://docs.thewalletcrew.io/developers-guides/scripting/globals.md) and [Modules](https://docs.thewalletcrew.io/developers-guides/scripting/modules.md) | Look up the globals (`fetch`, `console`, …) and the modules (`getSecret`, …)                    |

{% hint style="info" %}
The advanced configuration editor offers completion generated from the running platform; when the editor and a page disagree, the editor is the reference. See [How scripts run](https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md#editor-typings).
{% endhint %}

## Build checklist

Before writing scripts, settle the following items with the brand and its partners. A missing item is the usual origin of an unstable connector in production.

| Item                               | Expected output                                                                                                                                                                                              |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Identifier strategy                | Stable identifier fields (`customerId`, `membershipId`, `ticketId`, and so on) available on every pass-relevant record. They link wallet passes to source records over time.                                 |
| Data ownership                     | The source system and its owner are explicit for profile, loyalty, transaction and ticket data. The owner controls the business rules and the data quality.                                                  |
| Trigger model                      | A clear decision on how data is fetched (pull, push or lifecycle hooks) and which endpoint runs when: data provider, pipeline step, pass hooks, scheduled list. It also defines when updates are propagated. |
| API or event contract and security | The authentication, payload shape and error handling of each external call. Use API keys or OAuth, with the credentials stored as secrets.                                                                   |
| Operational ownership              | The team that monitors integration failures and retries, with the retry, timeout and monitoring behavior agreed.                                                                                             |

## FAQ

<details>

<summary><strong>Which language and version do scripts use?</strong></summary>

Scripts are plain JavaScript, with `async` / `await`, `const` and `let`, classes, arrow functions, template strings, destructuring, spread (`...`), optional chaining (`?.`) and `??`. They are executed by an embedded engine, not by Node.js: Node modules, `require`, the file system and browser APIs are not available. Only the globals and modules documented in this section exist.

Some recent syntax and built-ins are missing. A `catch` must name its error: `catch (error)` works, `catch {` is a syntax error. `Object.entries`, `Object.values`, `Object.fromEntries`, `Number.isFinite`, `Number.isInteger` and `String.prototype.replaceAll` are not available: use `Object.keys`, the global `isFinite` and `split` / `join` instead.

</details>

<details>

<summary><strong>Is there a test environment for scripts?</strong></summary>

Scripts follow the configuration: change them in a non-production tenant first, then copy the files to production. [Best practices](https://docs.thewalletcrew.io/developers-guides/scripting/best-practices.md#testing) lists what to check before the copy.

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