Member Hub · Documentation

Integration Guide

Published integration documentation for internal lookup consumers. Authentication, the GET /api/v1/member/lookup contract, response statuses, error shapes, rate limits, and rebuild-from-C7 operational notes.

Authentication

Two methods are supported for internal lookup consumers.

Staff session

Authenticated Clerk staff users may call the endpoint with their session cookie (browser) or Bearer token.

Cookie: Clerk session
Authorization: Bearer <clerk_session_token>

Internal API key

Service-to-service callers pass the shared internal key configured in Member Hub.

X-API-Key: <INTERNAL_API_KEY>
Authorization: Bearer <INTERNAL_API_KEY>

Endpoint

Internal member lookup by QR token. Serves members_index only — never calls Commerce7 live.

Member lookup by QR token

Serves members_index only — never calls Commerce7 live.

GET /api/v1/member/lookup?qr={token}

Parameter	Required	Description	Example
qr	Yes	Opaque base32 QR token value (128-bit, no PII)	ABCDEFGHIJKLMNOPQRSTUVWX

Response statuses

All successful lookups return HTTP 200 with a JSON body containing status.

Status values

When a member has dual membership (stored as "both" in the index), the lookup response returns membershipType: "wine".

Status	Meaning	Additional fields
Unknown token	Token not found in members_index	—
Revoked	Token was revoked	—
Inactive	Member exists but membership is inactive	—
Deactivated	Customer deactivated in Commerce7	—
Lookup eligible	Eligible member — membership details included	membershipType, tier, c7CustomerId

Response examples

Example JSON bodies returned by GET /api/v1/member/lookup.

Sample payloads

The ok example shows Wine Club precedence for dual membership.

{
  "status": "ok",
  "membershipType": "wine",
  "tier": "Gold",
  "c7CustomerId": "abc-123"
}

Errors

Authentication and validation failures return non-200 responses.

Error responses

Error bodies use a single error string field.

HTTP	Body	Cause
401	{ "error": "Unauthorized" }	Missing or invalid authentication
400	{ "error": "Invalid qr parameter" }	Missing or empty qr query parameter

Rate limits

Lookup is index-only; Commerce7 limits apply to sync operations only.

Limits by scope

Member lookup does not call Commerce7 and is not subject to C7 rate limits.

Scope	Limit
Member lookup (GET /api/v1/member/lookup)	Index-only — no Commerce7 rate limits apply to this endpoint
Commerce7 API (webhooks, QR write-back)	100 requests/min/tenant — handled with backoff in the C7 client

Operational notes

Logging, latency targets, and rebuilding the index from Commerce7.

Running the integration

Commerce7 is the source of truth; Postgres is a reverse index cache.

Lookup requests are logged to lookup_log with a hashed token (never raw), latency, result tier, and auth source.
Target p95 latency for lookup is 300ms.
Commerce7 remains the source of truth; Postgres members_index is a reverse index cache rebuilt via webhooks and nightly reconciliation.
To rebuild the index from C7: run the nightly reconciliation cron (/api/cron/reconcile) or replay from C7 customer and club membership exports.
Uptime monitors should GET /api/v1/member/lookup with X-API-Key, X-Uptime-Probe: 1, and the fixed probe qr token — see docs/operations/uptime-monitor.md.

Not the Tevalis till contract

This guide documents the internal Member Hub lookup API for staff systems and trusted services — not the Tevalis point-of-sale integration.

OpenAPI reference and machine-readable spec for tooling.

API Reference (OpenAPI)OpenAPI JSON