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

# Data objects

The shapes of values handed to scripts: the entity and its keys, identifiers versus additional data and metadata, and how dates, numbers and enums arrive.

Scripts receive objects built from .NET data, and what they write back is converted the other way. Most surprises come from a handful of facts: the entity is a flat dictionary of dotted keys, assigning `null` removes a key, enumerations arrive as numbers, dates are not `Date` instances, and a pass has three different places to keep data that look alike but do not behave alike.

<details>

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

* A script reads `entity['id.crm.customerId']` to look a customer up, and writes `entity['crm.tier']` for the template to display.
* A script deletes a stale value by assigning `null` to its key.

</details>

## The entity

The entity, also called the account, is the object most handlers receive: `entity` in `Fill` and `CreateOrUpdate`, `account` in `Validate`. It is a flat dictionary of keys to values: the platform stores whatever keys the enrolment form, the flows and the providers write, and there is no fixed schema.

Keys are read and written by name:

```js
const email = entity['email'];
const customerId = entity['id.crm.customerId'];
entity['crm.tier'] = 'gold';
```

Bracket access is the form that works for every key, including keys that contain dots or hyphens, which cannot be written with a dot. A key that is missing reads as `undefined`. Assigning `null` removes the key. Assigning `NaN` or an infinite number removes the key as well, because such values cannot be stored; the platform logs a warning that names the key. A value that has to be kept absent is therefore set to `null`, and a computed number is checked with the global `isFinite` before it is assigned (`Number.isFinite` is not available).

Nested dictionaries are wrapped in the same way, so a value that is itself a dictionary is read by key too. Indexing by key, `for...in`, spread (`{ ...x }`), `Object.assign` and `JSON.stringify` work on the wrapped dictionaries. `Object.keys` works on the entity but throws on the other dictionaries a script receives, such as the identifiers of a pass or the headers of a connection interceptor, so it is not used on them. Lists, such as a list member of a .NET object, are read by index, have a `length` and accept `push` and `map`, but `Array.isArray` returns `false` for them. A plain object assigned to a typed member, for example a nested block of a connector record, is converted to that type.

### Key conventions

Keys are free-form, but some prefixes carry a meaning for the platform.

| Key                                                               | Meaning                                                                                                                                                                                                              |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id.<name>`                                                       | An external identifier of the holder, such as `id.crm.customerId`. A pass carries identifiers, and the platform exposes each one to providers under the `id.` prefix                                                 |
| `email`, `phoneNumber`                                            | The holder's email and mobile phone number                                                                                                                                                                           |
| `consents_email`, `consents_sms`                                  | The holder's marketing consents, as the enrolment form collected them. A value may arrive as a boolean or as text, depending on the form                                                                             |
| `storeId`                                                         | The store the holder is attached to; the platform matches it against the tenant's stores configuration to put that store's data on the pass                                                                          |
| `authenticationToken`                                             | A token the platform issues for the holder's pages                                                                                                                                                                   |
| `neo.pass.id`, `neo.pass.passType`                                | Written by the platform, in a flow that creates or updates a pass, with the id and the pass type of that pass                                                                                                        |
| `neo.pass.state`, `neo.pass.Apple.state`, `neo.pass.Google.state` | Installation state, `Installed` or `Uninstalled`, written when a pass becomes installed on its first device or uninstalled on its last, for the providers that update an external system                             |
| `neo.lng`, `neo.src`, `neo.redirectId`                            | Context of the enrolment: language, source, redirect identifier. They are legacy names, listed in [Obsolete neostore names](https://docs.thewalletcrew.io/developers-guides/scripting/modules/obsolete-neo-names.md) |
| `debug.<name>`                                                    | Diagnostic payloads; they are never published under a provider namespace                                                                                                                                             |

The prefix `neostore` is the platform's former name and is kept in technical identifiers such as the `neo.` keys.

The `neo.pass.<device>.state` keys use the device name, `Apple` or `Google`, as in `neo.pass.Apple.state`. They exist only in the entity handed to the customer providers listed in `server/account.yml` when an installation change is mirrored to an external system, and in the entity of a connector mapper that mirrors the installation change (the Cegid Y2 mapper reads them, see [Cegid Y2 scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions/cegid-y2.md)): a script `Fill` registered for such a provider sees them, and a pass render does not. The value is a plain string.

Keys written by a script for templates should not use the reserved prefixes `id.`, `neo.` and `debug.`; they should use plain names, which the platform also publishes under the script's namespace (`memberLookup.points` for a key `points` written by the script `memberLookup`). Identifiers and `debug.*` keys are never prefixed.

{% hint style="warning" %}
Storing a whole API response on the entity, for instance under `debug.response`, makes the data larger for every consumer of the entity. Write the few values that the pass or the next step needs, and log a short message instead of the payload, without personal data.
{% endhint %}

## Identifiers, additional data and metadata

A pass keeps three kinds of data, which look similar in scripts but have different roles. The full description is in [Pass data and sync](https://docs.thewalletcrew.io/developers-guides/pass-architecture/pass-data-and-sync.md); the table below is the part scripts depend on.

| Kind            | What it is for                                                                                                                                                          | Seen by scripts as                                                                                                                                                        |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identifiers     | Tie the pass to a record in another system (CRM customer id, loyalty card number). Data providers use them to look the holder up                                        | `entity['id.<key>']` in a data provider; a plain object `{ key: value }` without the `id.` prefix in the hooks of the pass updater; the `Identifiers` member of an update |
| Additional data | Values stored on the pass itself, written by enrolment, imports, updates or the API. Templates read them as `additionalData.<key>`. They are never used to look data up | The `AdditionalData` member of an update (string to string; `null` removes a key)                                                                                         |
| Metadata        | Values the pass type computes at each update, stored so that passes can be searched and filtered and automations can react to them                                      | Not written by scripts; defined in the pass type                                                                                                                          |

An identifier is the way to say "this pass belongs to that customer". An additional data value is a stored attribute. A script that wants a value to survive on the pass returns it as additional data in an update, whereas a value written by a data provider exists only while the pass is rendered.

In an update, `Identifiers` selects the passes: `id` names one pass, and keys of the form `id.<name>` select every pass that carries all the listed identifiers. The shape is shared by the push updates and the bulk row transformer; see [Push updates](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/push-updates.md) and [Bulk pass update row transformation](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/bulk-pass-update-row-transformation.md).

## Values of the pass updater hooks

The hooks of the [pass updater](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/pass-updater.md) receive plain arguments rather than the entity:

| Argument                | Shape                                                                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `passId`                | String                                                                                                                                                                                                                                                             |
| `passType`              | String, the name of the pass type                                                                                                                                                                                                                                  |
| `identifiers`           | Object of string values, keyed without the `id.` prefix                                                                                                                                                                                                            |
| `creationDate`          | Date-like value (see below), in `OnPassCreated`                                                                                                                                                                                                                    |
| `device`                | Number: `0` for Apple, `2` for Google (install and uninstall hooks)                                                                                                                                                                                                |
| `additionalInformation` | Object with camelCase members: `registrationInformation` (`activeRegistrationCount`, the current registrations, and `totalRegistrationCount`, which never decreases) and, for installs, an optional `registrationSource` (`tags`, `medium`, `origin`, `userAgent`) |

`OnPassCreating` and `OnPassUpdating` are the only hooks whose result changes the pass: they return `{ PassType?, Identifiers? }`. `PassType` is applied only when it is a non-empty string. `Identifiers`, when it is not `null`, replaces all the identifiers of the pass, so an empty object wipes them. Returning `null` or nothing means no change.

## Dates

Dates received by a script are date-like objects: they carry the `toISOString`, `getTime` and `getFullYear` methods but are not instances of `Date`, so `date instanceof Date` is `false`. Calling the methods works, and `toISOString()` gives a string that can be compared, stored or returned.

Dates returned by a script are most reliably expressed as ISO 8601 strings with an explicit offset or `Z`, for example `'2026-03-01T10:00:00Z'`. A `Date` built from its parts is fragile: `new Date(2026, 3, 1)` is the first of April, because months start at zero, and it is interpreted in the time zone of the server. A benefit that carries a returned `Date` object is refused: see [Handlers](https://docs.thewalletcrew.io/developers-guides/scripting/handlers.md#return-values-conversion-by-member-name). The global `toDateTime(value)` converts a string, or a `Date`, to a UTC date-time that the platform understands; see [Utility globals](https://docs.thewalletcrew.io/developers-guides/scripting/globals/tools.md).

## Numbers

Numbers are JavaScript numbers in both directions. A returned number is cast to the numeric type the platform expects, so `3` is accepted for an integer and `2.5` for a decimal; a string such as `'3'` is converted too. Because `NaN` and the infinities have no stored form, they are dropped from the entity with a warning (see above).

Amounts and balances that have to be exact are best kept as integers in the smallest unit, or as strings carrying the formatted value, and formatted once, in the template.

## Enumerations

.NET enumerations arrive as numbers, never as names. The `device` argument of the install and uninstall hooks is `0` for Apple and `2` for Google. There is no other value. A comparison such as `device === 'apple'` never matches, and a strict comparison with the string `'0'` does not match either:

```js
const APPLE = 0;
const GOOGLE = 2;

async function onInstalled(passId, passType, identifiers, device) {
  const wallet = device === APPLE ? 'apple' : device === GOOGLE ? 'google' : 'other';
  console.info(`pass installed on ${wallet}`);
}
```

In the other direction, a string or a number returned for an enumeration member is converted to the enumeration when it names or numbers a valid value.

## FAQ

<details>

<summary><strong>Which data should be stored on the pass, and which should be fetched?</strong></summary>

Values that change often and belong to another system are best fetched by a data provider, with a cache. Values that the platform needs to search, filter or compare on, or that must remain visible when the other system is down, are stored as additional data through an update.

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