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

# Comarch scripts

Reference of the four Comarch scripts, customer mapper, location mapper, installation customer updater and coupon mapper: handlers and examples.

Four scripts adjust the Comarch connector. The customer mapper and the location mapper add Comarch attributes to the pass data, the wallet installation customer updater decides what changes on the Comarch customer when a pass is installed or removed, and the coupon mapper adjusts, or skips, the benefit each Comarch coupon becomes. This page is the reference for `extensions.comarch.customerMapper`, `extensions.comarch.locationMapper`, `extensions.comarch.walletInstallationCustomerUpdater` and `extensions.comarch.couponMapper`. The connector is described on the [Comarch extensibility page](https://docs.thewalletcrew.io/connectors/crm-and-fidelity/comarch/extensibility.md); the rules shared by every connector script are in [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md).

<details>

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

* A loyalty program adds a custom Comarch attribute to the pass data.
* A brand sets a `WALLET` attribute on the Comarch customer while at least one device holds the pass.
* A brand skips the coupons that have a given status, so that they never become benefits.

</details>

## Registration

| Key                                                    | Slot file                                      | Methods (required in **bold**)                       |
| ------------------------------------------------------ | ---------------------------------------------- | ---------------------------------------------------- |
| `extensions.comarch.customerMapper`                    | `comarch.customerMapper.js`                    | `MapFromComarch`, `MapTransactionBalanceFromComarch` |
| `extensions.comarch.locationMapper`                    | `comarch.locationMapper.js`                    | `MapFromComarch`                                     |
| `extensions.comarch.walletInstallationCustomerUpdater` | `comarch.walletInstallationCustomerUpdater.js` | `Update`                                             |
| `extensions.comarch.couponMapper`                      | `comarch.couponMapper.js`                      | **`MapFromComarch`**                                 |

The slots are the **Customer mapper**, **Location mapper**, **Wallet pass add/remove script** and **Coupon mapper** scripts of the **Advanced** tab of the Comarch settings editor, and are read and written with `GET` and `PUT /api/{tenantId}/admin/extensions/comarch/scripts`. When no script is registered for a key, the default behavior applies. The **Wallet pass add/remove script** and **Coupon mapper** slots appear only while their setting is on, and switching **Sync wallet attribute when a pass is added or removed** off deletes the add/remove script file.

## When it runs

| Script                                            | Runs                                                                                                                                                                                                                              |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customerMapper.MapFromComarch`                   | After the Comarch customer is fetched and the default `comarch.customer.*` fields are written                                                                                                                                     |
| `customerMapper.MapTransactionBalanceFromComarch` | After `comarch.customer.waitingToBookPoints` is written, only when **Retrieve customer transaction balance** is on. The raw balance is under `debug.comarch.customer.customerTransactionBalanceInformation`                       |
| `locationMapper.MapFromComarch`                   | After the store is fetched and the default `comarch.store.*` fields are written                                                                                                                                                   |
| `walletInstallationCustomerUpdater`               | On every pass installation and removal, on every device, while the Comarch setting **Sync wallet attribute when a pass is added or removed** is on, with a fresh Comarch record. Passes without a Comarch customer id are skipped |
| `couponMapper`                                    | For each coupon, at every pass creation and pass metadata update, while the Comarch setting **Sync Comarch coupons** is on. A used or cancelled coupon that never produced a benefit is skipped before the script is called       |

The customer mapper also runs on every refresh of a pass, including the refreshes started by the [Kafka real-time updates](https://docs.thewalletcrew.io/connectors/crm-and-fidelity/comarch/real-time-updates.md), so it stays short.

## Handlers

| Key                                 | Method                             | Parameters                         | Returns                                                    | Required | Sync or async |
| ----------------------------------- | ---------------------------------- | ---------------------------------- | ---------------------------------------------------------- | -------- | ------------- |
| `customerMapper`                    | `MapFromComarch`                   | `customer`, `account`              | nothing                                                    | Optional | Synchronous   |
| `customerMapper`                    | `MapTransactionBalanceFromComarch` | `{ Customer, Balance }`, `account` | nothing                                                    | Optional | Synchronous   |
| `locationMapper`                    | `MapFromComarch`                   | `location`, `account`              | nothing                                                    | Optional | Synchronous   |
| `walletInstallationCustomerUpdater` | `Update`                           | `status`, `customer`               | a `Customer` with only the properties to change, or `null` | Optional | Synchronous   |
| `couponMapper`                      | `MapFromComarch`                   | `coupon`, `benefit`                | the benefit to sync, or `null` to skip the coupon          | Required | Synchronous   |

* **Mappers.** `customer` and `location` are the raw Comarch objects, so any field of the Comarch payload can be used, not only the mapped ones. `account` is the flat wallet account (see [Data objects](https://docs.thewalletcrew.io/developers-guides/scripting/data-objects.md)). The mappers change `account` in place. The raw objects are visible for inspection under `debug.comarch.customer` and `debug.comarch.store`.
* **Installation updater.** `status` has camelCase members: `device` (`0` Apple, `2` Google), `event` (`0` installed, `1` removed), `activeRegistrationCount` and `totalRegistrationCount`. Both counts are combined across platforms: the active count is the current number of installs including this change, and the total count is the lifetime number of installs, which never decreases. The returned customer is sent to Comarch **as it is**, not compared with the current record, so the update must be safe to repeat. Returning `null` (or nothing) sends nothing. When the script is not registered, the write-back is skipped and logged at information level. A throw in `Update` is logged and the update is skipped.
* **Coupon mapper.** `coupon` has members such as `Id`, `CouponNumber`, `Type`, `TypeName`, `Status` (`I` issued, `U` used, `E` expired), `StatusName` and `AccountId`. Returning the benefit syncs it. Returning `null`, or nothing, skips the coupon, and a benefit that the script produced earlier for it is removed.

## Errors and edge cases

* **No script registered**: the default behavior applies. Without the installation updater, the install write-back is skipped.
* **The coupon mapper is missing while coupon sync is on**: the call fails with `method MapFromComarch missing`.
* **The updater returns a customer with every property**: all of them are sent. Return only what changes.

## Example

The installation updater sets a `WALLET` attribute to `Y` while at least one device holds the pass, and to `N` otherwise. The attribute code and its values are placeholders: use the ones defined in the brand's Comarch configuration.

```js
function update(status, customer) {
  const installed = status.activeRegistrationCount > 0;
  return { Attributes: [{ Code: 'WALLET', Value: installed ? 'Y' : 'N' }] };
}

export default function (context) {
  context.register('extensions.comarch.walletInstallationCustomerUpdater', {
    Update: update
  });
}
```

The coupon mapper skips the expired coupons (status `E`):

```js
function mapFromComarch(coupon, benefit) {
  if (coupon?.Status === 'E') {
    return null;
  }
  return benefit;
}

export default function (context) {
  context.register('extensions.comarch.couponMapper', {
    MapFromComarch: mapFromComarch
  });
}
```

## Common pitfalls

* The updater result is not idempotent: it is sent as it is on every install and uninstall, on every device.
* The coupon mapper forgets to return the benefit: returning nothing skips the coupon.
* A handler is declared `async`: the Comarch methods are synchronous, so the promise is not awaited.
* The slot's registration lines are still commented out.


---

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