Manage pass lifecycle with the API

Create, update, notify, deactivate, and track Apple Wallet and Google Wallet passes with The Wallet Crew API.

Manage pass lifecycle with the API

The Wallet Crew API manages a pass from creation to wallet removal. It supports pass updates, wallet notifications, and lifecycle events for Apple Wallet and Google Wallet.

Use this guide to choose the right lifecycle action. Use the API reference for schemas, parameters, and responses.

Real-world examples

• A retailer creates a loyalty pass using a CRM customer identifier.
• An airline updates gate information and sends a wallet refresh.
• An event platform records wallet removal through Pass:Uninstalled.

Before managing a pass

Passes use identifiers to connect each wallet pass to external records. These identifiers let connectors fetch the latest source data during rendering.

Review Pass data and sync before designing an integration. Use Structure to choose stable identifier keys.

Pass state model

The Wallet Crew has no universal pass state field. Pass data defines the state. Liquid templates map that data to native wallet fields.

Apple Wallet supports these state-related fields:

• voided — a boolean that marks the pass invalid in the wallet. Set it to false to reverse the change.
• expirationDate — an ISO 8601 date that defines when the pass expires.

Google Wallet supports these state-related fields:

• state — one of ACTIVE, COMPLETED, EXPIRED, or INACTIVE.
• validTimeInterval — the time window during which the pass remains valid.

Map the relevant fields in the Apple Wallet and Google Wallet templates. The displayed state changes only after a pass renders again.

The Wallet Crew has no soft-delete or archive state. The API does not delete pass records. To deactivate a pass, update the relevant platform state field.

Creating a pass

Create a pass through the operation below. Supply at least one external identifier from the source system.

The Wallet Crew validates identifiers through one of these authorization methods:

• HMAC signature
• Registered secret
• Security allowlist
• Pass.Write scope

A pass requires data at creation. The Wallet Crew fetches connector data lazily when the pass first renders. Include data that allows a connector to locate the external record.

Create a new pass.

post

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/api/{tenantId}/passes

Authorization: Requires Pass.Write scope OR valid identifier validation (HMAC signature, secret, or allowlisted unsigned).

Security: Each identifier must validate via: (1) HMAC (key.hmac), (2) registered secret (key.secret), (3) security allowlist, or (4) Pass.Write scope. Omit identifiers if JWT contains customer claims.

Pass Type: Template to use. Must match file in tenant server/passes/ config.

Use Cases: API-based pass creation; customer self-service with HMAC; bulk imports.

Example — create with HMAC-signed identifier:

POST /api/{tenantId}/passes?passType=loyalty
            
{
  "identifiers": {
    "shopify.customerId": "12345",
    "shopify.customerId.hmac": "{hmac-of-12345}"
  },
  "additionalData": { "loyaltyTier": "silver" }
}

Example — create with Pass.Write scope (no HMAC required):

POST /api/{tenantId}/passes?passType=loyalty
            
{
  "identifiers": { "shopify.customerId": "12345" },
  "additionalData": { "loyaltyTier": "silver" }
}

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

passTypestringOptional

Type of the pass to create. Must match a file in the tenant server/passes/ configuration.

Body

application/jsontext/jsonapplication/*+json

Data payload for pass creation operations.

additionalDataobject · nullableOptional

Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags).

extensionsobject · nullableOptional

Extensibility data related to this pass.

Responses

200

Pass created successfully.

text/plainapplication/jsontext/json

stringOptional

401

Identifiers cannot be validated and caller lacks Pass.Write scope.

text/plainapplication/jsontext/json

post/api/{tenantId}/passes

HTTPcURLJavaScriptPython

POST /api/{tenantId}/passes HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "extensions": null,
  "identifiers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "additionalData": null
}

application/jsontext/jsonapplication/*+json

text

Pass creation does not fetch connector data immediately. The first installation or render triggers that fetch.

Updating pass data

Use the operation below to update pass data and request a wallet refresh. Submitted fields merge with the existing pass data. Omitted fields remain unchanged. An empty value or null removes the submitted field.

Update a pass and optionally its type.

patch

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/api/{tenantId}/passes

Authorization: Requires Pass.Write scope.

Identification: Use internal id (e.g., id=Ed34kg3oA47) or external identifiers with id. prefix (e.g., id.y2.customerId=1233332). Multiple identifiers must match exactly one pass.

Data: Merged with existing data. Empty/null removes fields; omitted fields unchanged.

Metadata: Set options.UpdateMetadata=true for recomputation (slower). Set options.BypassQueue=true for synchronous updates instead of queueing.

Type: Optionally convert pass to different type.

Use Cases: Update identifiers/metadata; push notifications; type conversion; bulk updates; urgent changes.

Example — update by platform pass ID:

PATCH /api/{tenantId}/passes?id=xK9mP2nQr7sT
            
{
  "additionalData": { "loyaltyTier": "gold" },
  "options": { "updateMetadata": true }
}

Example — update by external identifier:

PATCH /api/{tenantId}/passes?id.shopify.customerId=12345
            
{
  "identifiers": { "email": "[email protected]" },
  "additionalData": { "loyaltyTier": "gold" },
  "options": { "updateMetadata": false }
}

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

passTypestringOptional

type of the pass to update. type name should be one of the file in the server/passes/ tenant configuration.

Body

application/jsontext/jsonapplication/*+json

Data payload for single pass update operations.

additionalDataobject · nullableOptional

Arbitrary data to persist with the pass (for example, loyalty tier, store code, or campaign flags).

passTypestring · nullableOptional

Optional pass type to convert the pass to.

updateMetadatabooleanOptionalDeprecated

Specifies if passes metadata should be updated. Updating metadata is time consuming and could be avoided for notification only push update

Default: false

bypassQueuebooleanOptionalDeprecated

Indicates whether the push update should bypass the queue and run immediately. Queuing helps protect the system load and should only be bypassed when required.

Default: false

Responses

200

Pass update enqueued or applied successfully.

No content

404

No pass found matching the provided identifiers.

text/plainapplication/jsontext/json

patch/api/{tenantId}/passes

HTTPcURLJavaScriptPython

PATCH /api/{tenantId}/passes HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 163

{
  "identifiers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "additionalData": null,
  "passType": null,
  "options": {
    "bypassQueue": false,
    "updateMetadata": true,
    "correlationId": null
  }
}

application/jsontext/jsonapplication/*+json

No content

Push notification behavior

Backend and device updates

Pass updates operate at two independent levels:

1. Backend update — The Wallet Crew updates the pass record.
2. Device notification — The Wallet Crew notifies wallet platforms when active registrations exist.

The backend update completes regardless of installation status. Device delivery depends on whether the pass remains installed.

Device notification

After the backend updates, The Wallet Crew attempts to notify Apple Wallet and Google Wallet. The notification depends on active registrations:

• An installed pass can receive an update through its wallet platform.
• An uninstalled pass has no active registrations, so no device notification is sent.
• A later installation receives the latest pass version from The Wallet Crew.

Queue and deduplication

The Wallet Crew queues updates by default with bypassQueue: false. The queue protects system throughput and deduplicates work. If another update reaches the same pass before the queued task runs, the queue skips the earlier task.

Set bypassQueue: true for urgent synchronous updates. Use it for changes such as boarding status updates that must reach the wallet immediately.

Re-rendering on device

A notification does not update a property directly. When a device receives a notification, its wallet requests the latest pass version. The Wallet Crew fetches fresh connector data before returning that version.

Backend updates persist. This supports safe updates while a pass is uninstalled.

For template mappings and pass fields, see Update pass data in templates.

Sending a standalone notification

Send a text notification without changing pass data with the operation below. The notification appears in the wallet application independently of a data update.

Use content for a plain string. Use localizedContent for an object keyed by ISO 639 language codes. Use one content format per request.

Send a notification to the pass identified by its pass identifier

put

https://app.neostore.cloudhttps://app-qa.neostore.cloud

/api/{tenantId}/passes/{passId}/notification

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

The internal identifier of the pass

tenantIdstringRequired

Body

application/jsontext/jsonapplication/*+json

contentstring · nullableOptional

Could be null if LocalizedContent is specified

localizedContentobject · nullableOptional

Localized notification content by language code. Key: ISO 639-1 code or "iso2-region" (e.g., "en", "en-US"). Value: The notification content for that language.

Responses

200

OK

No content

404

Not Found

text/plainapplication/jsontext/json

put/api/{tenantId}/passes/{passId}/notification

HTTPcURLJavaScriptPython

PUT /api/{tenantId}/passes/{passId}/notification HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 92

{
  "content": null,
  "localizedContent": null,
  "options": {
    "updateData": false,
    "correlationId": null
  }
}

application/jsontext/jsonapplication/*+json

No content

Wallet removal

When an end-user removes a pass, the wallet platform notifies The Wallet Crew. Apple sends an HTTP DELETE request to the Apple registrations route. Google sends a message with eventType = "del".

The Wallet Crew sends Pass:Uninstalled when the last active registration reaches zero. Removing a pass from one of two iPhones does not send the event.

The webhook payload includes:

• passId, passType, identifiers, and metadata
• device and deviceIdentifier — Google sets deviceIdentifier to null
• registrationInformation.activeRegistrationCount and registrationInformation.totalRegistrationCount

The Wallet Crew delivers the event through the configured webhook endpoint. The request includes X-NEOSTORE-EVENTNAME: Pass:Uninstalled.

Removing a pass from a wallet does not delete its The Wallet Crew record. The pass can be installed again later.

Configure endpoint delivery and validate signatures in Webhooks.

FAQ

Does updating pass data immediately change an installed pass?

No. The update creates a new pass version and triggers a wallet refresh. Apple Wallet or Google Wallet then requests that version.

Can a pass be deleted through the API?

No. The API does not delete pass records. Set the platform-specific state fields to deactivate a pass.

Why was a wallet update not delivered?

Push delivery requires an active provider registration. Confirm that the pass was installed on the relevant wallet platform.

Can I use failed updates to detect uninstalled passes?

No. Updates do not fail when a pass is uninstalled. The Wallet Crew processes the backend update successfully. No device push is sent when the pass has no active registrations.

Check installation status with the pass details endpoint. Alternatively, listen for Pass:Installed and Pass:Uninstalled events.