This documentation is currently under development. Certain sections are not yet complete and will be added shortly.
For the complete documentation index, see llms.txt. This page is also available as Markdown.
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.

1

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.

2

Open the API reference

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

Open API reference

3

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.

4

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

patch/api/{tenantId}/passes

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.

Common next steps

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

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.