# Custom connector

Custom connectors extend The Wallet Crew with tenant-side scripts. They are useful when pass data must be enriched from an external system or when custom logic must run when a pass is installed or uninstalled.

This pattern keeps the integration inside the tenant runtime. It avoids exposing connector logic in client-side code and makes external calls easier to control.

<details>

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

* A Brand enriches a loyalty pass with points and tier data from an external CRM.
* A partner fills a pass with profile attributes coming from a proprietary API.
* A team synchronizes pass installation status with a marketing or analytics platform.

</details>

## Requirements

To create a script, open **Settings → Advanced → Advanced Configuration**. This section contains the tenant configuration files.

Script files are stored under `/server/script/...`.

{% hint style="info" %}
`customProvider` is only an example name. You can replace every `customProvider` occurrence with the connector name that should be registered or you can keep it.
{% endhint %}

## Create the script file

In the file explorer, create a file such as `/server/script/customProvider.js`.

If the folder or file does not exist yet, create it first. To create a folder from the file explorer, enter the folder name followed by `/`.

## Register the connector

Once the script file exists, add the connector registration:

```js
export default function(context) {
  context.register('runtime.scriptable.customerProvider.customProvider', {
    Fill: fill
  });
  context.register('runtime.wallet.passUpdater', {
    OnPassInstalled: onPassInstalled,
    OnPassUninstalled: onPassUninstalled
  });
}
```

## Fill function

The `Fill` function is the entry point used to retrieve and inject external data into the pass lifecycle.

In practice, this function receives the current pass context, calls the required external services, and returns or applies the data needed by the connector. The exact implementation depends on the external system being connected.

The runtime contract for `Fill` is available in the [Fill function reference](https://app-qa.neostore.cloud/api/swagger/tenantConfiguration/index.html#section/Scripts/runtime.scriptable.customerPipelineElement.scriptId).

### Example implementation

This example reads the external identifiers that are added when a pass is created, calls an external API, and maps the response back into the entity.

```javascript
async function fill(entity) {
  const externalId = entity["id.externalId"];
  if (!externalId) {
    return false;
  }

  try {
    const res = await fetch("https://example.com/api/wallet", {
      Method: "GET",
      Headers: {
        "Content-Type": "application/json",
        "X-API-KEY": API_KEY,
      }
    });

    const item = JSON.parse(res.ResponseText)[0];

    entity.eventName = item?.eventName ?? `event ${externalId}`;
    entity.external_last_name = item?.lastName ?? null;
    entity.external_first_name = item?.firstName ?? null;
    entity.external_image_url = item?.imageUrl ?? null;
    entity.external_logo = item?.logo ?? null;
    entity.external_color = item?.color ?? null;
    entity.external_background_color = item?.backgroundColor ?? null;

    return true;
  } catch (e) {
    entity.external_error = `An error occurred while calling the external API: ${e}`;
    return true;
  }
}
```

## What this registration does

The script registers two runtime entry points. Each one serves a different purpose.

`runtime.scriptable.customerProvider.customProvider`

This registration exposes a function named `Fill`. The `Fill` function is used to populate passes with external data.

This is the place to call external APIs and enrich pass data with information coming from partner systems, CRM platforms, loyalty engines, or any other backend connected to the project.

`runtime.wallet.passUpdater`

This registration exposes two lifecycle hooks:

* `OnPassInstalled`
* `OnPassUninstalled`

These hooks are triggered when a pass is installed or uninstalled. They make it possible to run connector logic at the exact moment the wallet lifecycle changes.

Typical uses include synchronizing installation status, starting a welcome flow, or stopping reminder communications once the pass is already installed.

The runtime contract for these hooks is available in the [OnPassInstalled and OnPassUninstalled reference](https://app-qa.neostore.cloud/api/swagger/tenantConfiguration/index.html#section/Scripts/runtime.wallet.passUpdater).

For the full install and uninstall hook behavior, see [Pass installation and uninstallation hooks](/connect/custom-connector/installation-changed-extensibility.md).

## FAQ

<details>

<summary><strong>Does the script file need to be named <code>customProvider.js</code>?</strong></summary>

No. The filename can follow any naming convention used by the project. What matters is the runtime registration key used inside the script.

</details>

<details>

<summary><strong>Can <code>customProvider</code> be replaced with another connector name?</strong></summary>

Yes. Replace `customProvider` with the connector name that should be exposed by the runtime registration.

</details>

<details>

<summary><strong>When should <code>runtime.wallet.passUpdater</code> be registered?</strong></summary>

Register it when the integration must react to pass installation or uninstallation events. If only pass enrichment is needed, the customer provider registration may be enough.

</details>


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thewalletcrew.io/develop/guides/custom-connector.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.