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

# Handlers

How the platform calls script handlers, what happens when one is missing or throws, how return values are converted, and a table comparing every endpoint.

A handler is a function a script registers for the platform to call. The rules that decide whether the platform finds it, how it treats its return value and what it does when the handler is absent or fails are the same for every endpoint, but the outcomes differ from one endpoint to another: a missing handler can be a silent no-op for one endpoint and a hard error for the next.

## Naming: the exact method name

The platform calls a handler by the name of the method it needs, in PascalCase and case-sensitive: `Fill`, `Describe`, `GetPasses`, `CreateOrUpdate`, `OnPassCreating`, `GetBenefits`. The name is the property name in the object given to `context.register`, not the name of the JavaScript function that implements it.

```js
context.register('runtime.wallet.passUpdater', {
  OnPassInstalled: onInstalled,
});
```

Here `onInstalled` can be called anything. `OnPassInstalled` has to be written exactly. A property named `onPassInstalled`, or `OnPassinstalled`, is not found.

## Required, optional and no-op handlers

Each method of an endpoint falls into one of three categories, which decide what happens when the object registered by the script has no property of that name:

| Category | When the handler is missing                                                        | Typical methods                                                              |
| -------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| No-op    | The call returns at once, as if the handler had done nothing                       | `CreateOrUpdate`, `SendEmail`                                                |
| Optional | The call returns the default value: `null`, `false` or `0`                         | `Describe`, `GetThroughput`, `Transform`, the hooks of the pass updater      |
| Required | The call fails with the error `method <Name> missing`, when the handler is reached | `Fill`, `GetPasses`, `Validate`, `GetBenefits`, `Enrich`, `GetEmailTemplate` |

The **Missing handler** column of the endpoint table below gives the category of each method. An endpoint page documents the same information in its "Errors and edge cases" section.

## Several registrations of one key

The platform asks for one handler or for all of them, depending on the endpoint. For nearly all endpoints, the last registered handler is used; see [How scripts run](https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md#one-key-one-file) for the exceptions.

## Synchronous and asynchronous handlers

A handler can be an ordinary function or an `async` function. When it returns a promise, the platform waits for it. Most methods are asynchronous on the platform side, and for them an `async function` is the safe form: it is the form used by every example in this documentation, and a handler that does not need `await` can still be declared `async`.

Some methods are synchronous on the platform side, and for these a promise is wrong: the handler has to return the value itself, not a promise of it. They are:

| Method                                                                     | Reason                                                                                                               |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Describe` of the pass data provider and of the obsolete customer provider | The platform reads the namespace and fields from it synchronously, in the editor, at save and during each pass build |
| `GetThroughput` and `Transform` of the bulk pass update row transformer    | Called once per file and per row                                                                                     |

Connector methods are synchronous, except `GetContactIdentifiers` (Bloomreach), `GetPassType` (Aparté, Secutix) and the connection interceptors; see [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md).

### Time limit before the first `await`

A handler that runs for more than 5 000 ms before its first `await` throws: see [How scripts run](https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md#time-limits).

## Return values: conversion by member name

What a handler returns is converted to the .NET type the platform expects, and the conversion works by exact member name, case-sensitive. Two families of types exist, and the family decides the casing of the keys:

* Types declared without explicit script names use their .NET names, in PascalCase. A handler returning `{ PassType: 'x' }` is understood; `{ passType: 'x' }` is not. The pass updater result (`PassType`, `Identifiers`), the push-update request (`PassInformations`, `Throughput`) and the update information of a pass (`Identifiers`, `PassType`, `ThemeId`, `AdditionalData`, …) are in this family.
* Types that carry explicit script names use camelCase. The benefits returned by a benefit provider, the result of `Describe`, the result of the Apple pass resolver and the `additionalInformation` given to the install hooks are in this family.

The endpoint pages state the casing of each shape. When in doubt, the editor typings show the exact names.

The conversion follows a few rules that hold for every shape:

* A member that is absent in the returned object keeps its .NET default (`null`, `0`, `false`). Returning only the members that matter is normal.
* A member whose name is not part of the target type is ignored without any message. A misspelled key never produces an error: it produces a missing value.
* Numbers are cast to the numeric type of the target (integer, decimal, …). Strings are converted to numbers, booleans, enumerations, identifiers and dates when the target type needs it.
* Dates are returned as ISO 8601 strings; see [Data objects](https://docs.thewalletcrew.io/developers-guides/scripting/data-objects.md#dates).
* Arrays are returned as arrays; the elements are converted one by one with the same rules.
* A promise is awaited and its value converted. Handlers whose result is a boolean or a required object should return it on every path rather than rely on a default.

```js
async function getPasses() {
  return {
    Throughput: 3,
    PassInformations: [
      { Identifiers: { id: 'pass-1' }, AdditionalData: { tier: 'gold' } },
    ],
  };
}
```

### Casing of the shapes

The rule of the two families is spread over the endpoint pages. The table below gathers it; the `fetch` shapes are in [fetch](https://docs.thewalletcrew.io/developers-guides/scripting/globals/fetch.md#options-and-defaults).

| Shape                                                                                          | Casing                            |
| ---------------------------------------------------------------------------------------------- | --------------------------------- |
| Pass updater result (`PassType`, `Identifiers`)                                                | PascalCase                        |
| Push update result and update description (`PassInformations`, `Throughput`, `AdditionalData`) | PascalCase                        |
| Account validator errors (`Detail`, `Field`)                                                   | PascalCase                        |
| Link enricher `context` (`PassId`, `Device`, `Origin`)                                         | PascalCase                        |
| `buildEmail` result (`Subject`, `Body`)                                                        | PascalCase                        |
| `Describe` result, benefits, Apple pass resolver request and result                            | camelCase                         |
| `additionalInformation` of the install hooks (`registrationInformation`)                       | camelCase                         |
| Comarch `status`, Cegid UR `data.person.firstName`                                             | camelCase                         |
| Other vendor objects (`data.EmailData.Email`, `eventData.Name`)                                | PascalCase, the .NET member names |

## Throwing

A handler that throws is not caught by the engine; the exception propagates to the platform component that called it, which then decides. For some endpoints the error is logged and the platform carries on; for others it fails the request, the job or the flow step. The "script throws" column of the table below gives the outcome. As a rule, a handler that depends on a remote system catches the failure and reports it through its return value rather than throwing, unless failing is the correct outcome.

## Comparison of the endpoints

The table lists every runtime endpoint, with the handlers the platform calls and the behavior in each situation. Each key links to its page through [Runtime endpoints](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints.md).

| Key                                                                                             | Handlers                                                                                                     | Missing handler                      | No registration                                                          | Several registered       | Script throws                                                                                              |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `runtime.scriptable.passDataProvider.{scriptId}`                                                | `Fill(entity)` returns a boolean (required); `Describe()` (optional, synchronous)                            | `Fill` required                      | `Fill` behaves as `true`, nothing written (see the note below the table) | Last wins                | In a pass type's `dataProviders`, the entry fails and the pass render fails                                |
| `runtime.scriptable.customerProvider.{scriptId}` (obsolete, replaced by the pass data provider) | `Fill`, `Describe`                                                                                           | `Fill` required, `Describe` optional | Behaves as `true` when no pass data provider is registered either        | Last wins                | As the pass data provider                                                                                  |
| `runtime.scriptable.customerPipelineElement.{scriptId}`                                         | `CreateOrUpdate(entity)`                                                                                     | No-op                                | Nothing happens                                                          | Last wins                | The error reaches the flow step                                                                            |
| `runtime.scriptable.pushUpdates.{scriptId}`                                                     | `GetPasses()` returns `{ Throughput?, PassInformations }`                                                    | Required                             | The scheduler task logs an error and updates nothing                     | Last wins                | A throw in `GetPasses` fails the task; a failure on one row is logged and counted, the other rows continue |
| `runtime.scriptable.emailEngine`                                                                | `SendEmail(recipient, emailTemplate, data, cultures, buildEmail)`                                            | No-op: no email is sent              | The send fails with a "not registered" error                             | Last wins                | Propagates                                                                                                 |
| `runtime.scriptable.scriptableAccountValidator`                                                 | `Validate(account)` returns a list of `{ Detail, Field? }`                                                   | Required                             | The account is valid                                                     | Last wins                | Propagates                                                                                                 |
| `runtime.emailAccountChallenger.templateFinder`                                                 | `GetEmailTemplate(data, defaultTemplateName)` returns a name or `null`                                       | Required                             | The configured template name is used                                     | Last wins                | Propagates                                                                                                 |
| `runtime.wallet.linkUrlEnricher`                                                                | `Enrich(url, context)` returns a URL or `null`                                                               | Required                             | Default tracking parameters are appended                                 | Last wins                | Swallowed; the original URL is kept and a warning is logged                                                |
| `runtime.import.updatePasses.rowTransformer`                                                    | `GetThroughput(fileName)`, `Transform(row)` (both synchronous)                                               | Optional                             | Default CSV columns                                                      | Last wins                | The import stops at that row (**Import failed**); batches already handed over are applied                  |
| `runtime.benefit.benefitProvider`                                                               | `GetBenefits(passId, passType, identifiers)`                                                                 | Required                             | No-op                                                                    | Last wins                | Swallowed; the pass keeps its benefits                                                                     |
| `runtime.wallet.passUpdater`                                                                    | `OnPassCreating`, `OnPassCreated`, `OnPassUpdating`, `OnPassUpdated`, `OnPassInstalled`, `OnPassUninstalled` | Optional                             | No-op                                                                    | All run                  | Logged, that script is skipped, the operation continues                                                    |
| `runtime.wallet.applePassResolver`                                                              | `ResolveMissingPass(request)`                                                                                | Required                             | No recovery                                                              | Error when more than one | Wrapped in a generic error; the call is limited to 10 seconds                                              |
| `runtime.scriptable.benefitTemplateCodeGenerator.{templateId}`                                  | `Generate()` returns a string or `null`                                                                      | Required                             | A warning is logged and `null` is used                                   | Last wins                | Propagates                                                                                                 |

A script id with no registration counts as a provider that **found data** and wrote nothing, so a misspelled `scriptId` shows on the pass data page as found, with no variable. A provider that counts as found does not run again. Such an entry also counts for the rounds: it starts another round for the entries that found nothing.

Connector extension endpoints (`extensions.*`) follow the same rules; they are listed on [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md), with a sync or async column for each method.

{% hint style="warning" %}
"Propagates" means that the failure reaches the platform component that called the handler and fails its operation, which is visible to the caller of the request. Keep handlers of such endpoints defensive: validate inputs, catch the failures of remote calls, and return the documented neutral value.
{% endhint %}

## FAQ

<details>

<summary><strong>Does a handler have to return something?</strong></summary>

It depends on the method. `Fill` has to return `true` or `false` on every code path, so that every path says whether data was found. `false` means nothing was found; `true` is returned only when the data was found. `CreateOrUpdate` and the pass updater notifications return nothing. For hooks that may return a change (`OnPassCreating`, `OnPassUpdating`), the same neutral value, `null`, should be returned on every path where nothing changes.

</details>

<details>

<summary><strong>Can a handler be declared with parameters it does not use?</strong></summary>

Yes. Parameters are positional, and only the declared ones are read. Names are free; the order is the one in the endpoint page.

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