> 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/endpoints/bulk-pass-update-row-transformation.md).

# Bulk pass update row transformation

Read bulk update-passes CSV files with custom columns and set the pace of each file, with runtime.import.updatePasses.rowTransformer.

The bulk "update passes" import reads a CSV file, dropped for import (including through SFTP), and turns each row into an update of one or several passes. By default the columns must follow the [documented column reference](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/import-and-export/update-pass-using-flat-files.md). The row transformer lets a tenant script read files whose columns cannot be changed, typically an export from a CRM or a point-of-sale system, and choose the delivery pace of each file. This page is the reference for `runtime.import.updatePasses.rowTransformer`.

The row transformer is the right tool when the updates arrive as a file. When the list of passes comes from a query that a script can run itself on a schedule, [push updates](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/push-updates.md) avoid the file altogether.

<details>

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

* A point-of-sale system exports a nightly file with its own column names (`CARD_NO`, `BALANCE`); the script maps them to the pass identifier and to additional data.
* A CRM export carries the customer's language in one column and the notification text in another; the script builds the localized notification.
* Files whose name (the last segment of the path) starts with `priority-` are delivered faster than the routine ones.

</details>

## Registration

The key is `runtime.import.updatePasses.rowTransformer`. Registering it is enough: no configuration file refers to it, and from then on it applies to every "update passes" file of the tenant.

```js
export default function (context) {
  context.register('runtime.import.updatePasses.rowTransformer', {
    GetThroughput: (fileName) => null,
    Transform: (row) => null
  });
}
```

Both handlers are optional, and an omitted handler, or one that returns `null`, falls back to the platform's default behavior for that file or row.

## When it runs

The import runs in a background job when a file is dropped. `GetThroughput` is called once per file, before any row is read. `Transform` is then called once per row, in file order. The updates are handed over in batches of 1 000 rows, each pass update being planned at the file's pace, and delivered later like any other pass update.

## Handlers

| Method          | Parameters | Returns                                            | Required |
| --------------- | ---------- | -------------------------------------------------- | -------- |
| `GetThroughput` | `fileName` | a number or `null`, **synchronously**              | Optional |
| `Transform`     | `row`      | an update description or `null`, **synchronously** | Optional |

Both handlers are synchronous: they return their value directly, without `async` and without `await`, so they cannot call `fetch` or read a secret: data that must be looked up belongs in the file, or in a [pass data provider](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/pass-data-provider.md) that reads it when the pass is built. `fileName` is the path of the imported file within the import folder. `row` is the current CSV row as an object keyed by column name, every value a string.

## Return value

### Throughput

`GetThroughput` returns the number of pass updates delivered per second for the whole file: the updates are spread at that pace from the first row to the last, however many rows the file has. `null` keeps the tenant's default pace for pass updates, 6 per second unless the tenant's scheduler configuration sets another one. A value must be greater than zero; values above 1 000 are capped at 1 000.

### Update description

`Transform` returns an update description with PascalCase keys, or `null` to parse that row with the documented columns. Every key left out or `null` leaves the corresponding part of the pass unchanged.

The keys, their meaning and the validation rules are the ones of the [push updates update description](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/push-updates.md#return-value). The only difference is that `Identifiers` is not required here when `Transform` returns `null`, because the row is then parsed with the documented columns.

{% hint style="info" %}
In a CSV column, a single dash `-` removes the theme. A script returns an empty string `""` instead: the dash is a convention of the CSV columns only, so a script that returns `"-"` names a theme called `-`, and the row is refused if no such theme exists.
{% endhint %}

## Errors and edge cases

The object returned by `Transform` goes through the same checks as a row read from the documented columns. A row whose `PassType`, `ThemeId` or `BenefitTemplateId` does not exist on the tenant, or whose `NewIdentifiers` has an empty value, is **refused**: nothing is changed for it, the other rows carry on, and the import log counts it under its reason. A row whose identifiers match no pass counts as **No match**.

An error thrown by `Transform` is different. It means the script cannot handle the file, so the import stops at that row and the import log shows **Import failed**. The batches of 1 000 rows already handed over are still applied; the rows of the batch in progress are not. To leave a row out without stopping the file, the script returns it with an empty `Identifiers`: it targets no pass and counts as **No match**. An error thrown by `GetThroughput`, or a throughput of zero or less, fails the import too.

When a script maps the rows, the import log does not list ignored columns: which columns the script reads is up to the script.

* **Several files register the key**: the last registered wins, and the load order of files is not defined.

## Example

The file comes from a point-of-sale export with columns `CARD_NO`, `BALANCE`, `LANG` and `MESSAGE`. Rows without a card number are skipped as "No match", and rows of the documented format, recognized by their `id` column, are left to the default parsing.

```js
function getThroughput(fileName) {
  const name = fileName.split(/[\\/]/).pop();
  return name.startsWith('priority-') ? 20 : null;
}

function transform(row) {
  if (row.id !== undefined) {
    return null;
  }

  const cardNumber = (row.CARD_NO ?? '').trim();
  if (!cardNumber) {
    return { Identifiers: {} };
  }

  const message = (row.MESSAGE ?? '').trim();
  const language = (row.LANG ?? '').trim().toLowerCase();

  return {
    Identifiers: { 'id.pos.cardNumber': cardNumber },
    AdditionalData: { balance: (row.BALANCE ?? '').trim() || null },
    Notification: message || null,
    NotificationLocalizations: message && language ? { [language]: message } : null
  };
}

export default function (context) {
  context.register('runtime.import.updatePasses.rowTransformer', {
    GetThroughput: getThroughput,
    Transform: transform
  });
}
```

## Checking the result

The import log of the file counts the rows applied, refused, without match and failed, and lists the most frequent refusal reasons; the completion of the import also records whether a row transformer was used and the throughput it chose. A test file of a few rows, targeting test passes, validates a new script before a production file is dropped.

## Common pitfalls

* Identifier keys written without the `id.` prefix, so no pass matches.

## FAQ

<details>

<summary><strong>Can the same tenant import files of both formats?</strong></summary>

Yes. `Transform` returns `null` for rows it does not recognize, and those rows are parsed with the documented columns, as the example does with the `id` column.

</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/endpoints/bulk-pass-update-row-transformation.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.
