Pass

Retrieve passes with optional filtering, sorting, and pagination.

get

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

/api/{tenantId}/passes

Authorization: Requires Pass.Read scope.

Filtering: By identifiers (e.g., identifiers.email), metadata fields (e.g., metadata.loyaltyTier), pass type, or installation status (apple, google).

Sorting: By id, passType, creationDate, lastUpdateDate, apple, google, or any identifier/metadata field.

Pagination: Zero-based pageIndex and pageSize. Total count in x-pagination-total header.

Use Cases: Search passes by customer attributes; monitor installation status; filter by loyalty tier or campaign flag.

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

pageIndexinteger · int32Optional

Zero-based page index.

Default: 0

pageSizeinteger · int32Optional

Number of passes per page.

Default: 20

Responses

200

Paged list of passes returned successfully.

text/plainapplication/jsontext/json

Represents a pass returned by the API.

idstring · nullableOptional

Unique identifier of this pass

secretstring · nullableOptional

Secret of the Pass

creationDatestring · date-timeOptional

Date of pass creation

lastUpdateDatestring · date-timeOptional

Date of last update or pass creation when no update is present

passTypestring · nullableOptional

Type of pass

identifiersobject · nullableOptional

External identifiers

metadataobject · nullableOptional

Metadata

additionalDataobject · nullableOptional

Additional data

providersobject · nullableOptional

Installation date per provider

get

/api/{tenantId}/passes

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

Paged list of passes returned successfully.

[
  {
    "id": null,
    "secret": null,
    "creationDate": "2026-03-05T00:37:49.119Z",
    "lastUpdateDate": "2026-03-05T00:37:49.119Z",
    "passType": null,
    "identifiers": null,
    "metadata": null,
    "additionalData": null,
    "providers": null
  }
]

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.

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.

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: 60

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

application/jsontext/jsonapplication/*+json

text

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.

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

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: 133

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

application/jsontext/jsonapplication/*+json

No content

Retrieve the specified pass for the specified device.

get

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

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

Path parameters

passIdstringRequired

Serial number of the pass.

Pattern: ^[\w-]{5,50}$

tenantIdstringRequired

Query parameters

devicestringOptional

Target platform: apple, google, preview, or auto.

Tagsstring[]Optional

Source tags for categorizing installation source.

MediumstringOptional

Installation medium (e.g., email, sms, app).

OriginstringOptional

Installation origin or referrer.

UserAgentstringOptional

User agent string from the installation request.

Responses

200

OK

No content

get

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

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes/{passId} HTTP/1.1
Host: app.neostore.cloud
Accept: */*

200

OK

No content

Update a pass using its passId.

patch

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

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

Authorization: Requires Pass.Write scope.

Identification: Uses the pass's unique passId directly.

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 passes by internal ID; push notifications; type conversion; urgent changes.

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

passIdstringRequired

The unique identifier of the pass to update.

Pattern: ^[\w-]{5,50}$

tenantIdstringRequired

Query parameters

passTypestringOptional

Optional type of the pass to update. Type name should match a file in the server/passes/ tenant configuration.

Body

application/jsontext/jsonapplication/*+json

Responses

200

Pass update queued or completed successfully.

No content

404

Pass with the specified passId not found.

text/plainapplication/jsontext/json

patch

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

HTTPcURLJavaScriptPython

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

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

application/jsontext/jsonapplication/*+json

No content

Retrieve a WebSocket URL for pass-level notifications.

get

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

/api/{tenantId}/passes/{passId}/connect

Path parameters

passIdstringRequired

Serial number of the pass.

Pattern: ^[\w-]{5,50}$

tenantIdstringRequired

Responses

200

WebSocket URL returned successfully.

text/plainapplication/jsontext/json

Represents a Web PubSub connection response for a pass.

urlstring · nullableOptional

WebSocket URL to connect for pass notifications.

404

Pass not found.

text/plainapplication/jsontext/json

get

/api/{tenantId}/passes/{passId}/connect

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes/{passId}/connect HTTP/1.1
Host: app.neostore.cloud
Accept: */*

{
  "url": null
}

Retrieve aggregated pass data from all registered data providers.

get

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

/api/{tenantId}/passes/{passId}/data

Path parameters

passIdstringRequired

Serial number of the pass.

Pattern: ^[\w-]{5,50}$

tenantIdstringRequired

Responses

200

OK

No content

get

/api/{tenantId}/passes/{passId}/data

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes/{passId}/data HTTP/1.1
Host: app.neostore.cloud
Accept: */*

200

OK

No content

Retrieve the raw persisted pass document for diagnostics.

get

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

/api/{tenantId}/passes/{passId}/data/raw

Path parameters

passIdstringRequired

Serial number of the pass.

Pattern: ^[\w-]{5,50}$

tenantIdstringRequired

Responses

200

Raw pass document returned.

No content

get

/api/{tenantId}/passes/{passId}/data/raw

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes/{passId}/data/raw HTTP/1.1
Host: app.neostore.cloud
Accept: */*

200

Raw pass document returned.

No content

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

Redirect to a web page that lets the user view and download the pass.

get

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

/api/{tenantId}/passes/{passId}/view

Path parameters

passIdstringRequired

tenantIdstringRequired

Responses

302

Found

404

Not Found

text/plainapplication/jsontext/json

get

/api/{tenantId}/passes/{passId}/view

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes/{passId}/view HTTP/1.1
Host: app.neostore.cloud
Accept: */*

No content

Retrieve multiple passes for the specified device.

get

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

/api/{tenantId}/passes/{passIds}

Path parameters

passIdsstring[]Required

Collection of pass identifiers with parsing support.

Pattern: ^[\w-]{5,50},([\w-]{5,50},?)+$

tenantIdstringRequired

Query parameters

devicestringOptional

Target platform: apple or google.

Tagsstring[]Optional

Source tags for categorizing installation source.

MediumstringOptional

Installation medium (e.g., email, sms, app).

OriginstringOptional

Installation origin or referrer.

UserAgentstringOptional

User agent string from the installation request.

Responses

200

OK

No content

get

/api/{tenantId}/passes/{passIds}

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes/{passIds} HTTP/1.1
Host: app.neostore.cloud
Accept: */*

200

OK

No content

Retrieve a Wallet Crew passId from external identifiers.

get

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

/api/{tenantId}/passes/findPass

Path parameters

tenantIdstringRequired

Query parameters

passTypestringOptional

Optional pass type to restrict the search.

Responses

200

OK

text/plainapplication/jsontext/json

stringOptional

204

No Content

get

/api/{tenantId}/passes/findPass

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes/findPass HTTP/1.1
Host: app.neostore.cloud
Accept: */*

text

Retrieve passes using a supplier key or comma-separated pass IDs.

get

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

/api/{tenantId}/passes/getPasses

Two Modes:

• Supplier Mode: When provider specified, value passed to registered IPassSupplier (e.g., order lookup) returns associated pass IDs. Can optionally create missing passes.

• Direct Mode: When provider null, value treated as comma-separated pass IDs.

Preview: When includePreview=true, includes title, subtitle, colors, header text, enabled status for UI rendering.

Use Cases: E-commerce (order → passes); subscriptions (subscription → passes); mobile preview data; loyalty programs (member → passes).

Path parameters

tenantIdstringRequired

Query parameters

valuestringOptional

Key supplied to the provider to resolve passIds.

providerstringOptional

Provider name registered in DI. If null, value is treated as comma-separated passIds.

includePreviewbooleanOptional

When true, include preview details for each pass.

Default: false

Responses

200

Pass identifiers retrieved successfully.

text/plainapplication/jsontext/json

itemsanyOptional

get

/api/{tenantId}/passes/getPasses

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes/getPasses HTTP/1.1
Host: app.neostore.cloud
Accept: */*

200

Pass identifiers retrieved successfully.

[]

Send a notification to the corresponding pass

put

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

/api/{tenantId}/passes/notification

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

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/notification

HTTPcURLJavaScriptPython

PUT /api/{tenantId}/passes/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

Push update for passes matching the filter.

post

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

/api/{tenantId}/passes/pushUpdate

Authorization: Requires Pass.Write scope.

Filtering: Same as GetPasses—identifiers, metadata, pass type, installation status.

Async: Updates are queued. 200 response means scheduled, not complete. Monitor via statistics endpoint.

Data Merge: Merged into each matching pass. Set UpdateMetadata=true for recomputation (slower). Adjust Throughput for concurrency.

Bulk Operations: Ideal for campaigns, loyalty updates, seasonal offers. Use CorrelationId for tracking.

Use Cases: Campaign push; loyalty tier changes; offer refresh; bulk metadata updates.

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

Body

application/jsontext/jsonapplication/*+json

Data payload for multi-pass (bulk) update operations.

Responses

200

Passes scheduled for update; returns the count in the response body.

text/plainapplication/jsontext/json

passCountinteger · int32Optional

Count of passes scheduled for update.

post

/api/{tenantId}/passes/pushUpdate

HTTPcURLJavaScriptPython

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

{
  "identifiers": null,
  "additionalData": null,
  "passType": null,
  "options": {
    "throughput": 1,
    "updateMetadata": true,
    "correlationId": null
  }
}

application/jsontext/jsonapplication/*+json

200

Passes scheduled for update; returns the count in the response body.

{
  "passCount": 1
}

Cancel a running push update operation.

post

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

/api/{tenantId}/passes/pushUpdate/{correlationId}/cancel

Authorization: Requires Pass.Read scope.

Cancellation: Marks operation for cancellation. May take time if updates already dispatched.

Correlation Id: Use the id from push update schedule or statistics.

Use Cases: Stop campaign on config error; cancel nightly batch; prevent updates on security issue.

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

correlationIdstringRequired

CorrelationId used when scheduling the push update.

tenantIdstringRequired

Responses

204

Cancellation request accepted.

post

/api/{tenantId}/passes/pushUpdate/{correlationId}/cancel

HTTPcURLJavaScriptPython

POST /api/{tenantId}/passes/pushUpdate/{correlationId}/cancel HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

204

Cancellation request accepted.

No content

Retrieve execution statistics for recent push update operations.

get

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

/api/{tenantId}/passes/pushUpdate/status

Authorization: Requires Pass.Read scope.

Statistics: Operation id, correlationId, start/last activity, pass count, completed count, error count, Apple/Google deployment counts, cancellation status.

Ordering: Sorted descending by start date (most recent first).

Use Cases: Monitor batch progress; track campaign deployment; identify failures; audit history.

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Responses

200

Statistics retrieved successfully.

text/plainapplication/jsontext/json

Aggregated status of a push update operation.

idstring · nullableOptional

Unique operation identifier.

operationNamestring · nullableOptional

Operation name/category.

operationDatastring · nullableOptional

Correlation ID for tracking related updates.

startDatestring · date-timeOptional

Operation start timestamp.

lastActivitystring · nullableOptional

Last activity timestamp.

passCountinteger · int32Optional

Total passes scheduled for update.

completedinteger · int32Optional

Number of passes successfully updated.

errorsinteger · int32Optional

Number of passes with update errors.

appleinteger · int32Optional

Number of Apple Pass updates deployed.

googleinteger · int32Optional

Number of Google Pass updates deployed.

isCanceledbooleanOptional

Whether the operation was cancelled.

get

/api/{tenantId}/passes/pushUpdate/status

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes/pushUpdate/status HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

Statistics retrieved successfully.

[
  {
    "id": null,
    "operationName": null,
    "operationData": null,
    "startDate": "2026-03-05T00:37:49.119Z",
    "lastActivity": null,
    "passCount": 1,
    "completed": 1,
    "errors": 1,
    "apple": 1,
    "google": 1,
    "isCanceled": true
  }
]

Get pass distribution statistics

get

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

/api/{tenantId}/passes/stats

Returns aggregated counts of passes by installation status and platform.

Authorization

Requires Pass.Read scope.

Metrics Explained

• Total: All passes created (regardless of installation)

• Active: Passes currently installed on at least one device

• Apple: Passes installed on Apple Wallet

• Google: Passes installed on Google Wallet

Filtering

Optional passType parameter filters statistics to a specific pass type (e.g., "loyalty", "coupon").

Performance Note

This endpoint queries all passes and may be slow for large datasets. For production dashboards, consider using the Insights API with pre-aggregated queries.

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Query parameters

passTypestringOptional

Optional pass type filter (must match a tenant pass configuration file).

Responses

200

OK

text/plainapplication/jsontext/json

Get statistics about pass usage

get

/api/{tenantId}/passes/stats

HTTPcURLJavaScriptPython

GET /api/{tenantId}/passes/stats HTTP/1.1
Host: app.neostore.cloud
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

OK

{
  "count": {
    "total": 1,
    "active": 1,
    "apple": 1,
    "google": 1
  }
}