Getting started with the API

Make a first tenant-scoped API call against an existing pass in The Wallet Crew.

Getting started with the API

The Wallet Crew API gives developers programmatic control over passes. Pass creation is supported through the Cinto SDK, connectors, and POST /passes. Use POST /passes for backend-driven flows. See Pass lifecycle → Creating a pass.

Every API endpoint is scoped to a tenant. All calls include a {tenantId} path segment and an API key issued for that tenant. A tenant is an isolated workspace on the platform, often one brand or one region. If the tenant model is not familiar, start with Key concepts.

Real-world examples

• Trigger a pass refresh after a loyalty balance changes in a CRM.
• Record an in-store or venue scan from a POS or access control system.
• Send a push notification to a specific pass holder after an operational event.

Prerequisites

Before making a first API call, make sure these items already exist:

• A pass template configured in the back-office.
• At least one pass created through the Cinto SDK documentation, a connector, or POST /passes.
• An API key for the tenant.

Step 1 — Get the API key

In the back-office, go to Settings → API Keys & Secrets → API Keys.

Create a new API key. The key is automatically scoped to the tenant currently selected in the back-office. Copy the key when it is created. It is not shown again.

API keys carry permissions. A key without the required permissions returns 401 or 403. Use the API reference to confirm endpoint-specific requirements. A dedicated API key permissions page will be added separately.

Step 2 — Understand the base URL

The OpenAPI operations below include the production base URL. Replace {tenantId} with the tenant identifier. This identifier is the slug used in the back-office URL. For example, if the back-office URL contains /tenant/my-brand/, the tenantId is my-brand.

Every API endpoint is tenant-scoped. A key issued for one tenant cannot access another tenant's data.

Step 3 — Authenticate

Include the API key in every request using the X-API-KEY header.

If the key is missing or invalid, the API returns 401.

Step 4 — Understand pass identifiers

The API identifies passes through external identifiers — keys that link a pass to source systems such as a CRM ID, loyalty number, or ticket ID. Most endpoints accept an external identifier to target the correct pass.

Some endpoints also use the internal passId. This is common for direct operations such as sending a notification to a specific pass.

Common first calls

Force a pass update

A forced update is often the best first call when passes already exist. It validates tenant scoping, authentication, and provider refresh on a real pass.

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

This call tells the platform to re-fetch data from configured providers, rebuild the pass, and push the updated version to the device.

Record a scan

When a pass barcode is scanned at a point of sale or access control system, record the event through the Scan API.

Record a pass barcode scan event

post

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

/api/{tenantId}/scans

Records scan events when pass barcodes/QR codes are scanned. Scans are correlated to passes and generate scan completion events for downstream systems (redemption, attendance tracking, etc.).

Authorization

Requires PassScan.Scan scope

Required scopes

This endpoint requires the following scopes:

Authorizations

admin-bearerapiKey

OAuth2implicitRequired

Authorization URL:

Path parameters

tenantIdstringRequired

Body

application/jsontext/jsonapplication/*+json

datastring · min: 3 · max: 2048Required

Raw Data of the scan value

typestring · enumRequired

Type of data

Possible values:

Responses

201

Scan successfully recorded; pass identifier returned

text/plainapplication/jsontext/json

passIdstringRequired

Identifier of the pass

400

Invalid scan request (data too short/long, missing type)

text/plainapplication/jsontext/json

401

Not authorized or invalid credentials

text/plainapplication/jsontext/json

404

No pass found with matching scan data

text/plainapplication/jsontext/json

500

Processing error during scan event generation

post/api/{tenantId}/scans

HTTPcURLJavaScriptPython

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

{
  "data": "text",
  "type": "manual"
}

application/jsontext/jsonapplication/*+json

{
  "passId": "text"
}

Send a push notification

Use the notification endpoint to send a push notification to a specific pass holder.

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

API reference

The full API reference is available under Developers → API Reference.

Use it for endpoint details, request bodies, response schemas, and permission requirements.

Open the API reference

FAQ

Can the API create a new pass?

Yes. Pass creation is supported through the Cinto SDK, connectors, and POST /passes. Use POST /passes for backend-driven flows. See Pass lifecycle → Creating a pass.

What is the best first API call?

A forced update on an existing pass is usually the best first call. It validates tenant scope, authentication, and the render path on a real pass.

Should integrations start with passId or external identifiers?

Most integrations start with external identifiers because they already exist in source systems. Use passId when a direct pass operation needs the internal identifier.