GuideAPI

Developer guide

Start with The Wallet Crew APIs, authentication, and the main integration paths.

Developer guide

This section focuses on API integrations with The Wallet Crew. It covers authentication, the API reference, a first request, and the main paths to follow next.

Open API reference Start quickstart

Real-world examples

Create a loyalty pass after signup or checkout.
Update pass fields after a CRM, ticketing, or POS event.
Forward wallet lifecycle events to a backend, CRM, or analytics stack.

Start here

Most developer projects follow the same path.

Get credentials

Generate an API key from the admin console in Settings → Security → API Keys.

For most first integrations, the API key is sent in the X-API-KEY header.

Open the API reference

Use the API reference to inspect endpoints, request bodies, response schemas, and live examples.

Open API reference

Make a first request

Start with an existing pass. This is the fastest way to validate tenant access, authentication, and update behavior without mixing creation logic into the first test.

Continue with Getting started with the API.

Expand the integration

Once the first management call works, move to creation flows, updates, webhooks, scans, and reporting.

Authentication

The main developer entry point uses an API key. Generate the key from the admin console, then send it in the X-API-KEY header.

Some tenant-scoped APIs can use other authentication models or extra scopes. When that happens, the endpoint guide or reference is the source of truth.

For a first integration, start with APIs documented around X-API-KEY. This is the usual path for pass management, webhooks, scans, and the interactive API reference.

Quickstart

The fastest validation flow is to start with a pass that already exists, trigger a management call, then confirm the result on that pass.

The most common first call is a pass refresh:

Update a pass and optionally its type.

patch

/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

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

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.

patch/api/{tenantId}/passes

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
  }
}

No content

This validates tenant scope, API key authentication, and the update pipeline on a real pass. Use Getting started with the API for the end-to-end setup.

If no pass exists yet, start with Enrolment flows or Connector-triggered pass creation.

API reference

Use the API reference when the exact payload shape, response schema, or endpoint behavior matters.

Main entry points

Developer guides

These pages cover the main integration patterns.

Key concepts for tenant scope, identifiers, templates, and pass lifecycle basics.
Getting started with the API for the first tenant-scoped calls on passes that already exist.
Enrolment flows for pass creation during hosted or custom enrolment journeys.
Connector-triggered pass creation for source-driven issuance based on upstream events.
Update pass data in templates for updating pass data and rendering it in templates.
Templating engine for supported DotLiquid syntax, custom filters, and the minify tag.
Webhooks for real-time event delivery.
Scan API for barcode and QR scan ingestion.
Insights API for logs, events, and metrics queries.
Custom connectors for tenant-side integration logic.

Common next steps

After the first request succeeds, the next step usually depends on the integration goal.

If passes already exist, start with Getting started with the API.
If pass issuance starts in a signup, checkout, or hosted form, use Enrolment flows.
If pass issuance starts from a source-system event, use Connector-triggered pass creation.
To keep wallet content fresh, continue with Update pass data in templates.
To notify other systems in real time, use Webhooks.

FAQ

How is authentication retrieved?

Generate an API key from the admin console, then send it in X-API-KEY for the main platform APIs documented in the quickstart flow.

Where is the API reference?

Use API reference for the main API entry point.

What is the best first API call?

A forced update on an existing pass is usually the best first call because it validates tenant access, authentication, and the update path without depending on a creation flow.