Scan API

Record barcode/QR scans to validate passes and trigger downstream events (redemption, attendance, CRM signals).

Scan API

The Scan API records a barcode or QR scan, then correlates it to a pass. This creates a reliable “in-store / at-venue” signal that downstream systems can use for redemption flows, attendance tracking, or CRM automation.

Real-world examples

• Retail loyalty: record a scan at checkout to trigger post-visit automation.
• Event entry: record gate scans to track attendance and prevent reuse.
• Voucher redemption: record scans to mark an offer as consumed.

When Scan API is needed

Barcode/QR hardware can read the value displayed on a pass. The Scan API is the piece that makes that scan actionable in The Wallet Crew.

When the Scan API is invoked, The Wallet Crew can:

• identify which pass was scanned
• record the scan event with timestamp and symbology
• emit downstream events for connected systems

The Scan API does not replace operational validation logic. It provides a scan record and correlation. Redemption rules, anti-fraud, and privilege consumption depend on the chosen workflow.

Endpoint

The Scan API is available through this tenant-scoped operation:

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

Authentication and authorization

The Scan API requires an identity allowed to record scans.

Common patterns are:

• API key authentication (X-API-KEY) for server-to-server calls from a POS backend.
• OAuth 2.0 Bearer token for admin/user identities.

The effective authorization model depends on tenant configuration. In the OpenAPI definition, this endpoint requires the PassScan.Scan scope.

Request fields

The operation accepts two fields:

• data: the raw decoded value read by the scanner.
• type: the scan input type (symbology).

type values

type is an enum. Common values are:

• qrcode
• pdf417
• code128
• ean13
• datamatrix
• nfc
• manual (when staff types a code)

data is treated as an opaque identifier. Keeping it stable matters more than keeping it human-readable. Formatting changes (trim, leading zeros, separators) are common causes of correlation failures.

Response

The operation returns the correlated pass identifier. It returns 404 when correlation fails.

Implementation notes

A scanning system can call the Scan API either directly (when network access is available) or via a backend relay.

Calling from a backend relay is common. It keeps secrets out of scanning devices and allows enrichment, logging, and retry policies.

Validate the integration

A minimal validation sequence is:

1. Use a real pass issued by The Wallet Crew.
2. Scan its barcode/QR and capture the decoded value.
3. Use the Scan API operation with data and type.
4. Confirm a 201 response and a non-null passId.
5. Confirm the downstream signal is received (for example, wallet_scanned in Bloomreach).

Troubleshooting

404 Not Found

The scanned value did not match any pass.

Common causes are barcode formatting differences, missing prefixes/suffixes, or a mismatch between template barcode configuration and scanner decoding.

400 Bad Request

The payload failed validation.

Common causes are missing fields, data length outside limits, or an invalid type.

401 Unauthorized

The credentials are missing, invalid, or do not have the required scope.

FAQ

Does every barcode scan trigger a CRM event?

Only scans recorded through the Scan API are known to The Wallet Crew as scan events.

When recorded, the scan can be forwarded to connected systems such as Bloomreach as a wallet_scanned event.

Should the Scan API be called from the scanning device or from a backend?

A backend relay is the most common setup because it keeps API keys server-side and allows retries.

Direct calls from devices can work, but it increases secret handling and device management constraints.

What should be stored in data?

The raw decoded value that is configured in the pass barcode/QR.

Keeping that value stable across systems is the key requirement.