API Reference

REST API for creating and managing Apple Wallet and Google Wallet passes.

All requests and responses use JSON. Include Content-Type: application/json on requests with a body.

Authentication

The API uses two types of Bearer keys:

Authorization: Bearer wk_xxxxxxxxxxxxxxxxxxxxxxxx

Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxx

Keep both keys secret — anyone holding them can manage your workspaces and passes.

Errors

All errors return a consistent JSON body with a SCREAMING_SNAKE_CASE code, a human-readable message, and a unique request ID:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "template_id is required",
    "request_id": "req_01j9abc..."
  }
}

Rate limits

Requests are rate-limited per API key. When exceeded the API returns 429 rate_limited. Implement exponential backoff and retry after a short delay.

Create a new account and a default workspace. The api_key (sk_) and workspace_id are returned only once — store them securely.

Request body

Response 201

{
  "id": "acc_01j9...",
  "name": "Acme Corp",
  "email": "hello@acme.com",
  "workspace_id": "ws_01j9...",
  "api_key": "sk_xxxxxxxxxxxxxxxxxxxxxxxx",
  "webhook_secret": "whsec_xxxxxxxxxxxxxxxx",
  "portal_url": "/portal",
  "created_at": "2025-01-15T10:00:00.000Z"
}

api_key and webhook_secret are shown only on creation.

Retrieve your account details.

Response 200

{
  "id": "acc_01j9...",
  "name": "Acme Corp",
  "email": "hello@acme.com",
  "plan": "starter",
  "trial_ends_at": null,
  "api_key_prefix": "sk_a1b2c3d4",
  "webhook_url": "https://example.com/hooks",
  "created_at": "2025-01-15T10:00:00.000Z",
  "updated_at": "2025-01-15T10:00:00.000Z"
}

Update account settings. Only provided fields are changed.

Request body

Response 200

{ "id": "acc_01j9...", "name": "Acme Corp", "webhook_url": "...", "updated_at": "..." }

When rotate_webhook_secret: true, the response also includes webhook_secret — store it immediately as it is not shown again.

Permanently delete the account and all associated workspaces, passes, and device registrations. This cannot be undone.

Response 200

{
  "deleted": true,
  "deleted_passes": 42,
  "deleted_registrations": 87
}

Invalidate the current sk_ key and issue a new one. The old key stops working immediately. The new key is shown only once.

Response 200

{
  "api_key": "sk_yyyyyyyyyyyyyyyyyyyyyyyy",
  "message": "API key rotated. Store the new key — it will not be shown again."
}

Upload Apple Wallet and/or Google Wallet signing credentials. All binary or multi-line values must be base64-encoded. Only the fields you provide are updated — existing credentials are preserved. Account-level credentials are used by all workspaces that have Use account credentials enabled.

Apple Wallet fields

Google Wallet fields

Response 200

{
  "updated": ["apple_p12_cert", "apple_pass_type_identifier", "apple_team_id"]
}

List all workspaces for the account, along with the account's operation pool summary.

Response 200

{
  "workspaces": [
    {
      "id": "ws_01j9...",
      "name": "Production",
      "is_default": true,
      "operations_allocated": 5000,
      "operations_used": 120,
      "api_key_prefix": "wk_a1b2c3d4",
      "use_account_credentials": true,
      "created_at": "2025-01-15T10:00:00.000Z"
    }
  ],
  "total_ops": 10000,
  "allocated": 5000,
  "unallocated": 5000
}

Create a new workspace. Returns the workspace wk_ API key once — save it immediately.

Request body

Response 201

{
  "workspace": {
    "id": "ws_01j9...",
    "name": "Staging",
    "is_default": false,
    "operations_allocated": 1000,
    "operations_used": 0,
    "api_key_prefix": "wk_a1b2c3d4",
    "use_account_credentials": true,
    "created_at": "2025-06-01T12:00:00.000Z"
  },
  "api_key": "wk_xxxxxxxxxxxxxxxxxxxxxxxx"
}

Retrieve a single workspace.

Response 200

{ "workspace": { "id": "ws_01j9...", "name": "Production", ... } }

Update workspace name or operation allocation. Only provided fields are changed.

Request body

Response 200

{ "workspace": { "id": "ws_01j9...", "name": "Production (updated)", ... } }

Delete a workspace and all its passes. The default workspace cannot be deleted.

Response 200

{ "ok": true, "deleted_passes": 15 }

Invalidate the workspace's current wk_ key and issue a new one. The old key stops working immediately.

Response 200

{
  "api_key": "wk_yyyyyyyyyyyyyyyyyyyyyyyy",
  "message": "Save the new api_key — it will not be shown again"
}

List all pass templates in the workspace.

Response 200

{
  "data": [
    {
      "id": "tmpl_a1b2c3d4",
      "name": "Loyalty Card",
      "pass_style": "storeCard",
      "variable_schema": [
        { "name": "member_name", "type": "text", "required": true },
        { "name": "points",      "type": "text", "required": false },
        { "name": "tier",        "type": "text", "required": false }
      ],
      "created_at": "2025-01-15T10:00:00.000Z",
      "updated_at": "2025-06-01T09:00:00.000Z",
      "last_pushed_at": "2025-06-01T09:00:00.000Z"
    }
  ],
  "total": 1
}

Retrieve a single template including its full variable schema.

Response 200

{
  "id": "tmpl_a1b2c3d4",
  "name": "Loyalty Card",
  "pass_style": "storeCard",
  "variable_schema": [
    { "name": "member_name", "type": "text", "required": true },
    { "name": "points",      "type": "text", "required": false }
  ],
  "created_at": "2025-01-15T10:00:00.000Z",
  "updated_at": "2025-06-01T09:00:00.000Z",
  "last_pushed_at": null
}

List all passes issued from a specific template, with full identity and variable fields. Supports pagination.

Query parameters

Response 200

{
  "data": [ { "id": "pass_01j9...", "email": "jane@example.com", "variables": { "points": "1,250" }, ... } ],
  "total": 847,
  "limit": 50,
  "offset": 0
}

Auth: wk_ key

Create a new pass template. Returns the created template.

Request body

missing_placeholder_behavior

Example — nested body shape (recommended)

{
  "name": "Coffee Club",
  "pass_type": "loyalty",
  "platforms": ["apple", "google"],
  "module_mode": "loyalty_module",
  "loyalty_scheme_id": "ls_123",
  "template": {
    "content": { "title": "{{brand_name}}", "points_label": "Points" },
    "appearance": { "background_color": "#4A90D9" },
    "assets": {
      "icon": { "source": "https://example.com/icon.png" }
    }
  },
  "defaults": { "brand_name": "Acme Coffee" },
  "missing_placeholder_behavior": "error"
}

Example — legacy flat shape

{
  "name": "Coffee Rewards Card",
  "pass_data": {
    "pass_style": "storeCard",
    "description": "Coffee Rewards",
    "... other pass fields": "..."
  },
  "variable_schema": [
    { "name": "points", "label": "Points Balance", "type": "string" }
  ],
  "module_mode": "template_only"
}

Response 201 Created

{
  "id": "tmpl_a1b2c3d4",
  "name": "Coffee Rewards Card",
  "pass_style": "storeCard",
  "placeholder_schema": { ... },
  "variable_schema": [
    { "name": "points", "label": "Points Balance", "type": "string" }
  ],
  "module_mode": "template_only",
  "created_at": "2025-06-01T12:00:00.000Z",
  "updated_at": "2025-06-01T12:00:00.000Z"
}

Auth: wk_ key

Update an existing template. All fields are optional — only provided fields are updated.

Request body

Response 200

{
  "id": "tmpl_a1b2c3d4",
  "name": "Coffee Rewards Card (updated)",
  "pass_style": "storeCard",
  "placeholder_schema": { ... },
  "variable_schema": [ ... ],
  "module_mode": "loyalty_module",
  "created_at": "2025-06-01T12:00:00.000Z",
  "updated_at": "2025-06-16T09:00:00.000Z"
}

Auth: wk_ key

Delete a template. This does not affect already-issued passes.

Response 200

{
  "deleted": true
}

Issue a personalised pass from a template. If a pass already exists for this email (or external_id), it is updated and pushed to installed devices instead of creating a duplicate — making this endpoint safe to call repeatedly.

Variable values are substituted into any {variable_name} placeholders in the template at issue time.

Request body

Example request

{
  "template_id": "tmpl_a1b2c3d4",
  "email":       "jane@example.com",
  "first_name":  "Jane",
  "last_name":   "Smith",
  "external_id": "usr_999",
  "tags":        ["vip", "london"],
  "variables": {
    "points": "1,250",
    "tier":   "Gold"
  },
  "overrides": {
    "content": {
      "headerField": "{{tier}} MEMBER",
      "subtitle":    "{{first_name}} — {{points}} pts"
    }
  }
}

Overrides are deep-merged into the template before {{placeholder}} substitution, so they can contain their own placeholders. In the example above, {{tier}} and {{first_name}} are resolved from data and recipient just like any other variable.

Response 201 — created

{
  "pass_id":     "pass_01j9...",
  "external_id": "usr_999",
  "status":      "active",
  "apple": {
    "available":    true,
    "download_url": "https://api.walletpassapi.com/v1/passes/pass_01j9.../pkpass"
  },
  "google": {
    "available": true,
    "save_url":  "https://pay.google.com/gp/v/save/eyJhbGc..."
  },
  "created_at": "2025-06-01T12:00:00.000Z"
}

Response 200 — updated existing pass

{
  "pass_id":     "pass_01j9...",
  "external_id": "usr_999",
  "status":      "active",
  "apple": {
    "available":    true,
    "download_url": "https://api.walletpassapi.com/v1/passes/pass_01j9.../pkpass"
  },
  "google": {
    "available": true,
    "save_url":  "https://pay.google.com/gp/v/save/eyJhbGc..."
  },
  "created_at": "2025-01-15T10:00:00.000Z"
}

List all passes in the workspace, newest first. Each pass includes full identity and variable fields.

Query parameters

Response 200

{
  "data": [
    {
      "id": "pass_01j9...",
      "template_id": "tmpl_a1b2c3d4",
      "serial_number": "SN-XXXXXXXX",
      "pass_type": "storeCard",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "sms_mobile": null,
      "external_id": "usr_999",
      "variables": { "points": "1,250", "tier": "Gold" },
      "tags": ["vip", "london"],
      "device_count": 1,
      "pkpass_url": "https://api.walletpassapi.com/v1/passes/pass_01j9.../pkpass",
      "created_at": "2025-06-01T12:00:00.000Z",
      "updated_at": "2025-06-01T12:00:00.000Z"
    }
  ],
  "pagination": { "total": 847, "limit": 50, "offset": 0, "has_more": true }
}

Retrieve a pass with full identity, variable, device, and wallet URL fields.

Response 200

{
  "pass_id":     "pass_01j9...",
  "template_id": "tmpl_a1b2c3d4",
  "external_id": "usr_999",
  "status":      "active",
  "recipient": {
    "email":      "jane@example.com",
    "first_name": "Jane",
    "last_name":  "Smith",
    "sms_number": null
  },
  "data": {
    "points": "1,250",
    "tier":   "Gold"
  },
  "module": {
    "mode":             "loyalty_module",
    "loyalty_member_id": "lm_01j9..."
  },
  "apple":  { "download_url": "https://api.walletpassapi.com/v1/passes/pass_01j9.../pkpass" },
  "google": { "save_url":     "https://pay.google.com/gp/v/save/..." },
  "tags": ["vip", "london"],
  "created_at": "2025-06-01T12:00:00.000Z",
  "updated_at": "2025-06-01T12:00:00.000Z"
}

Update a pass and push the change silently to all installed Apple Wallet devices. Pass variables to re-substitute from the template. Pass identity fields to update the person record. Pass silent: true to skip the Apple push.

Request body

Example — update points balance

{
  "variables": { "points": "2,000" }
}

Response 200

{
  "pass_id": "pass_01j9...",
  "status":  "active",
  "updated": true,
  "apple":  { "updated": true },
  "google": { "updated": true }
}

If any Apple push notifications failed, a push_errors array is also present.

Delete a pass and send a removal push to registered Apple Wallet devices.

Response 200

{ "deleted": true, "push_sent_to": 1 }

Push a notification message to all devices holding this pass. The message appears on the lock screen and is written to a back field on the pass.

Request body

Response 200

{
  "ok": true,
  "push_sent_to": 1,
  "pkpass_url": "https://.../pkpass",
  "google_save_url": "https://pay.google.com/..."
}

Download the signed .pkpass bundle. This URL is intentionally public — link to it in email or a web page so recipients can tap to add the pass to Apple Wallet.

Response 200

Binary .pkpass file with Content-Type: application/vnd.apple.pkpass.

Generate a fresh Google Wallet JWT and save URL. Use google_save_url as the href for a Save to Google Wallet button.

Response 200

{
  "google_jwt": "eyJhbGciOiJSUzI1NiJ9...",
  "google_save_url": "https://pay.google.com/gp/v/save/eyJhbGc..."
}

Returns paginated event history for a pass — issuance, updates, device registrations, and more.

Query parameters

Response 200

{
  "data": [
    {
      "id": "evt_01j9...",
      "pass_id": "pass_01j9...",
      "event_type": "pass.issued",
      "created_at": "2025-06-01T12:00:00.000Z"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Queue a batch of up to 1,000 passes for async creation.

Request body

Example

{
  "passes": [
    { "template_id": "tmpl_a1b2c3d4", "email": "alice@example.com", "variables": { "points": "500" } },
    { "template_id": "tmpl_a1b2c3d4", "email": "bob@example.com",   "variables": { "points": "1200" } }
  ]
}

Response 202 Accepted

{
  "job_id": "job_01j9...",
  "status": "queued",
  "pass_count": 2,
  "created_at": "2025-06-01T12:00:00.000Z"
}

Poll the status of a batch job. Status transitions: queued → processing → completed or failed.

Response 200

{
  "job_id": "job_01j9...",
  "status": "completed",
  "pass_count": 2,
  "completed_count": 2,
  "failed_count": 0,
  "results": [
    { "index": 0, "status": "ok",    "id": "pass_01...", "error": null, "error_message": null },
    { "index": 1, "status": "ok",    "id": "pass_02...", "error": null, "error_message": null }
  ],
  "created_at": "2025-06-01T12:00:00.000Z",
  "completed_at": "2025-06-01T12:00:05.000Z"
}

Auth: wk_ key

Marks a pass as voided and pushes the voided state to all installed Apple Wallet devices. Fires a pass.voided webhook. This action cannot be undone. No request body is required.

Response 200

{
  "pass_id": "pass_01j9...",
  "status":  "voided"
}

Response 409 Conflict

{
  "error": {
    "code": "PASS_ALREADY_VOIDED",
    "message": "This pass has already been voided.",
    "request_id": "req_01j9abc..."
  }
}

Auth: sk_ key

Returns all named API keys for the account. Raw key values are never returned after creation.

Response 200

[
  {
    "id":           "key_01j9...",
    "name":         "CI/CD key",
    "scope":        "workspace",
    "workspace_id": "ws_01j9...",
    "last_used_at": "2025-06-14T10:22:00.000Z",
    "revoked_at":   null,
    "created_at":   "2025-05-01T09:00:00.000Z"
  }
]

Auth: sk_ key

Creates a new named API key. The raw key value is returned only once in this response — store it securely.

Request body

Example

{
  "name":         "CI/CD key",
  "scope":        "workspace",
  "workspace_id": "ws_01j9..."
}

Response 201 Created

{
  "id":    "key_01j9...",
  "name":  "CI/CD key",
  "scope": "workspace",
  "key":   "wk_live_..."
}

Auth: sk_ key

Permanently revokes a named API key. Any requests using this key will immediately receive a 401 Unauthorized response.

Response 200

{
  "revoked": true
}

Auth: sk_ key

Returns all registered webhook endpoints for the account.

Response 200

[
  {
    "id":           "whe_01j9...",
    "name":         "Production",
    "url":          "https://yourapp.com/webhooks/wallet",
    "events":       ["pass.created", "pass.updated"],
    "workspace_id": null,
    "is_active":    true,
    "created_at":   "2025-05-01T09:00:00.000Z"
  }
]

Auth: sk_ key

Registers a new webhook endpoint. The webhook_secret for signature verification is returned only once — store it securely.

Request body

Example

{
  "url":          "https://yourapp.com/webhooks/wallet",
  "name":         "Production",
  "events":       ["pass.created", "pass.updated"],
  "workspace_id": null
}

Response 201 Created

{
  "id":             "whe_01j9...",
  "name":           "Production",
  "url":            "https://yourapp.com/webhooks/wallet",
  "events":         ["pass.created", "pass.updated"],
  "workspace_id":   null,
  "is_active":      true,
  "webhook_secret": "whsec_...",
  "created_at":     "2025-06-01T09:00:00.000Z"
}

Auth: sk_ key

Updates a registered endpoint. All fields are optional — only provided fields are changed.

Request body

Response 200

{
  "id":             "whe_01j9...",
  "name":           "Production",
  "url":            "https://yourapp.com/webhooks/wallet",
  "events":         ["pass.created", "pass.updated", "pass.deleted"],
  "is_active":      true,
  "webhook_secret": "whsec_..."
}

webhook_secret is only present in the response when rotate_secret: true was sent.

Auth: sk_ key

Deletes a registered endpoint. All future deliveries to this endpoint are stopped immediately.

Response 200

{
  "deleted": true
}

Auth: sk_ key

Returns the last 50 delivery attempts for this endpoint, newest first. Use this to debug failed deliveries.

Response 200

[
  {
    "id":         "del_01j9...",
    "event":      "pass.created",
    "status":     200,
    "succeeded":  true,
    "attempt":    1,
    "error":      null,
    "created_at": "2025-06-14T11:00:00.000Z"
  },
  {
    "id":         "del_01j8...",
    "event":      "pass.updated",
    "status":     503,
    "succeeded":  false,
    "attempt":    3,
    "error":      "upstream connect error or disconnect/reset before headers",
    "created_at": "2025-06-14T10:55:00.000Z"
  }
]

Auth: sk_ key

Fires a test event to the endpoint URL and logs the delivery. Useful for verifying your endpoint is reachable and correctly validating signatures.

Response 200 — delivered

{
  "delivered": true,
  "status": 200
}

Response 200 — failed

{
  "delivered": false,
  "error": "Connection refused"
}

Auth: wk_ key

Create a new loyalty scheme.

Request body

Response 201 Created

{
  "id": "ls_01j9...",
  "name": "Coffee Rewards",
  "points_label": "Stars",
  "workspace_id": "ws_01j9...",
  "template_id": "tmpl_a1b2c3d4",
  "created_at": "2025-06-01T12:00:00.000Z"
}

Auth: wk_ key

List all loyalty schemes in the workspace.

Response 200

{
  "data": [
    {
      "id": "ls_01j9...",
      "name": "Coffee Rewards",
      "points_label": "Stars",
      "workspace_id": "ws_01j9...",
      "template_id": "tmpl_a1b2c3d4",
      "member_count": 142,
      "created_at": "2025-06-01T12:00:00.000Z"
    }
  ],
  "total": 2
}

Auth: wk_ key

Retrieve a single loyalty scheme including member count.

Response 200

{
  "id": "ls_01j9...",
  "name": "Coffee Rewards",
  "points_label": "Stars",
  "workspace_id": "ws_01j9...",
  "template_id": "tmpl_a1b2c3d4",
  "member_count": 142,
  "created_at": "2025-06-01T12:00:00.000Z"
}

Auth: wk_ key

Update an existing loyalty scheme. All fields are optional — only provided fields are changed.

Request body

Response 200

{
  "id": "ls_01j9...",
  "name": "Coffee Rewards (updated)",
  "points_label": "Stars",
  "workspace_id": "ws_01j9...",
  "template_id": "tmpl_a1b2c3d4",
  "updated_at": "2026-06-17T09:00:00.000Z"
}

Auth: wk_ key

Delete a loyalty scheme.

Response 200

{
  "deleted": true
}

Auth: wk_ key

List all loyalty members in the workspace. Supports limit (default 50, max 100) and offset pagination.

Query parameters

Response 200

{
  "data": [
    {
      "id": "pass_01j9...",
      "scheme_id": "ls_01j9...",
      "points": 1250,
      "email": "jane@example.com",
      "external_id": "usr_999",
      "created_at": "2025-06-01T12:00:00.000Z",
      "updated_at": "2025-06-01T12:00:00.000Z"
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

Auth: wk_ key

Retrieve a loyalty member including current points balance and tier.

Response 200

{
  "id": "lm_01j9...",
  "scheme_id": "ls_01j9...",
  "pass_id": "pass_01j9...",
  "email": "jane@example.com",
  "points_balance": 100,
  "tier": "Gold",
  "joined_at": "2025-06-01T12:00:00.000Z"
}

Auth: wk_ key

Adjust a member's points balance. Positive delta earns points, negative spends. Returns 422 insufficient_points if the resulting balance would be negative.

Two request formats are accepted:

Format A — delta (simple)

Format B — spec-canonical (typed)

Example (Format A)

{
  "delta": 50,
  "reason": "purchase",
  "reference_id": "order_123",
  "idempotency_key": "txn_abc"
}

Example (Format B)

{
  "type": "earn_points",
  "points": 50,
  "external_id": "order_123"
}

Response 200

{
  "member_id": "lm_01j9...",
  "delta": 50,
  "balance_after": 150,
  "transaction_id": "lt_01j9..."
}

Response 422

{
  "error": {
    "code": "INSUFFICIENT_POINTS",
    "message": "Insufficient points balance.",
    "request_id": "req_01j9abc..."
  }
}

Auth: wk_ key

List point transactions for a loyalty member. Supports limit (default 50, max 100) and cursor pagination.

Response 200

{
  "data": [
    {
      "id": "lt_01j9...",
      "delta": 50,
      "balance_after": 150,
      "reason": "purchase",
      "reference_id": "order_123",
      "created_at": "2025-06-01T12:00:00.000Z"
    }
  ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Auth: wk_ key

Create a new coupon scheme.

Request body

Response 201 Created

{
  "id": "cs_01j9...",
  "name": "Summer Sale",
  "coupon_type": "single_use",
  "offer": "20% off your next purchase",
  "valid_from": null,
  "redemption_limit": 1,
  "expires_at": "2026-08-31T23:59:59.000Z",
  "workspace_id": "ws_01j9...",
  "template_id": "tmpl_a1b2c3d4",
  "created_at": "2025-06-01T12:00:00.000Z"
}

Auth: wk_ key

List all coupon schemes in the workspace.

Response 200

{
  "data": [
    {
      "id": "cs_01j9...",
      "name": "Summer Sale",
      "redemption_limit": 1,
      "expires_at": "2026-08-31T23:59:59.000Z",
      "workspace_id": "ws_01j9...",
      "template_id": "tmpl_a1b2c3d4",
      "redemption_count": 38,
      "created_at": "2025-06-01T12:00:00.000Z"
    }
  ],
  "total": 3
}

Auth: wk_ key

Retrieve a single coupon scheme including redemption count.

Response 200

{
  "id": "cs_01j9...",
  "name": "Summer Sale",
  "redemption_limit": 1,
  "expires_at": "2026-08-31T23:59:59.000Z",
  "workspace_id": "ws_01j9...",
  "template_id": "tmpl_a1b2c3d4",
  "redemption_count": 38,
  "created_at": "2025-06-01T12:00:00.000Z"
}

Auth: wk_ key

Update an existing coupon scheme. All fields are optional — only provided fields are changed.

Request body

Response 200

{
  "id": "cs_01j9...",
  "name": "Summer Sale (updated)",
  "redemption_limit": 2,
  "expires_at": "2026-09-30T23:59:59.000Z",
  "workspace_id": "ws_01j9...",
  "template_id": "tmpl_a1b2c3d4",
  "updated_at": "2026-06-17T09:00:00.000Z"
}

Auth: wk_ key

Delete a coupon scheme.

Response 200

{
  "deleted": true
}

Auth: wk_ key

Record a coupon redemption for a pass. Returns 422 if the scheme is expired or the pass has reached its redemption limit.

Request body

Example

{
  "scheme_id": "cs_01j9...",
  "reference_id": "pos_transaction_456",
  "idempotency_key": "redeem_abc"
}

Response 201 Created

{
  "redemption_id": "cr_01j9...",
  "pass_id": "pass_01j9...",
  "scheme_id": "cs_01j9...",
  "redeemed_at": "2025-06-01T12:00:00.000Z"
}

Errors 422

{ "error": "scheme_expired" }

{ "error": "redemption_limit_reached" }

Auth: wk_ key

List redemptions for a pass. Optionally filter by scheme_id query parameter.

Response 200

{
  "data": [
    {
      "id": "cr_01j9...",
      "scheme_id": "cs_01j9...",
      "scheme_name": "Summer Sale",
      "redeemed_at": "2025-06-01T12:00:00.000Z",
      "reference_id": "pos_transaction_456"
    }
  ]
}

Auth: sk_ key

Returns an account-wide usage summary including total operations, allocation, and per-workspace breakdown.

Response 200

{
  "plan": "starter",
  "total_ops": 10000,
  "ops_used": 1420,
  "ops_remaining": 8580,
  "billing_period_start": "2026-06-01T00:00:00.000Z",
  "billing_period_end": "2026-07-01T00:00:00.000Z",
  "workspaces": [
    { "id": "ws_01j9...", "name": "Production", "ops_used": 1200 },
    { "id": "ws_02j9...", "name": "Staging",    "ops_used": 220 }
  ]
}

Auth: sk_ key

Returns a usage summary for a specific workspace.

Response 200

{
  "workspace_id": "ws_01j9...",
  "workspace_name": "Production",
  "ops_allocated": 5000,
  "ops_used": 1200,
  "ops_remaining": 3800,
  "billing_period_start": "2026-06-01T00:00:00.000Z",
  "billing_period_end": "2026-07-01T00:00:00.000Z"
}

Auth: wk_ key

Returns credential metadata for the workspace — which providers are configured and key identifiers. Raw credential values are never returned.

Response 200

{
  "apple": {
    "configured": true,
    "pass_type_identifier": "pass.com.example.mypass",
    "team_id": "XXXXXXXXXX",
    "apns_key_id": "YYYYYYYYYY"
  },
  "google": {
    "configured": true,
    "issuer_id": "3388000000012345678",
    "service_account_email": "wallet@my-project.iam.gserviceaccount.com"
  }
}

Auth: wk_ key

Save Apple Wallet signing credentials for the workspace. All binary values must be base64-encoded. Replaces any existing Apple credentials.

Request body

Response 200

{ "ok": true }

Auth: wk_ key

Save Google Wallet signing credentials for the workspace. All binary values must be base64-encoded. Replaces any existing Google credentials.

Request body

Response 200

{ "ok": true }

Auth: wk_ key

Remove Apple signing credentials from the workspace. The workspace will fall back to account-level credentials if available.

Response 200

{ "deleted": true }

Auth: wk_ key

Remove Google signing credentials from the workspace. The workspace will fall back to account-level credentials if available.

Response 200

{ "deleted": true }

Overview

Set a webhook_url on your account or workspace and the API will POST a JSON payload whenever a notable event occurs.

Payload envelope

{
  "id":           "evt_01j9...",
  "type":         "pass.updated",
  "account_id":   "acc_01j9...",
  "workspace_id": "ws_01j9...",
  "created_at":   "2025-06-01T12:00:00.000Z",
  "data":         { ... }
}

Note: the envelope field is type (not event).

Signature verification

Every delivery includes three headers:

• WalletPassAPI-Signature: v1=<hex-digest> — HMAC-SHA256 of timestamp.body
• WalletPassAPI-Timestamp: <unix-epoch> — seconds since epoch
• WalletPassAPI-Event-Id: evt_<id> — unique event identifier

The signature is computed as: HMAC-SHA256(secret, timestamp + "." + rawBody)

import crypto from 'crypto';

function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers['walletpassapi-timestamp'];
  const signature = headers['walletpassapi-signature']; // "v1="
  const expected  = 'v1=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Your webhook_secret is returned when you create an account or rotate it via PUT /v1/accounts/me with rotate_webhook_secret: true.

Events

{
  "id":           "evt_01j9...",
  "type":         "pass.created",
  "account_id":   "acc_01j9...",
  "workspace_id": "ws_01j9...",
  "created_at":   "2025-06-01T12:00:00.000Z",
  "data": {
    "pass_id":         "pass_01j9...",
    "pkpass_url":      "https://.../pkpass",
    "google_save_url": "https://pay.google.com/gp/v/save/..."
  }
}

{
  "id":           "evt_01j9...",
  "type":         "pass.updated",
  "account_id":   "acc_01j9...",
  "workspace_id": "ws_01j9...",
  "created_at":   "2025-06-01T12:05:00.000Z",
  "data": {
    "pass_id":         "pass_01j9...",
    "pkpass_url":      "https://.../pkpass",
    "google_save_url": "https://pay.google.com/gp/v/save/..."
  }
}

{
  "id": "evt_01j9...", "type": "pass.create_failed",
  "account_id": "acc_01j9...", "workspace_id": "ws_01j9...",
  "created_at": "2025-06-01T12:00:00.000Z",
  "data": { "error_code": "SIGNING_FAILED", "template_id": "tmpl_..." }
}

{
  "id": "evt_01j9...", "type": "pass.update_failed",
  "account_id": "acc_01j9...", "workspace_id": "ws_01j9...",
  "created_at": "2025-06-01T12:00:00.000Z",
  "data": { "pass_id": "pass_01j9...", "error_code": "SIGNING_FAILED" }
}

{
  "id": "evt_01j9...", "type": "pass.deleted",
  "account_id": "acc_01j9...", "workspace_id": "ws_01j9...",
  "created_at": "2025-06-01T12:10:00.000Z",
  "data": { "pass_id": "pass_01j9..." }
}

{
  "id": "evt_01j9...", "type": "coupon.redemption_failed",
  "account_id": "acc_01j9...", "workspace_id": "ws_01j9...",
  "created_at": "2025-06-01T12:00:00.000Z",
  "data": { "pass_id": "pass_01j9...", "scheme_id": "cs_01j9...", "error_code": "SCHEME_EXPIRED" }
}

{
  "id": "evt_01j9...", "type": "loyalty.transaction.created",
  "account_id": "acc_01j9...", "workspace_id": "ws_01j9...",
  "created_at": "2025-06-01T12:00:00.000Z",
  "data": { "member_id": "lm_01j9...", "transaction_id": "lt_01j9...", "delta": 50, "balance_after": 150 }
}

{
  "id": "evt_01j9...", "type": "device.registered",
  "account_id": "acc_01j9...", "workspace_id": "ws_01j9...",
  "created_at": "2025-06-01T12:00:00.000Z",
  "data": { "pass_id": "pass_01j9...", "device_library_identifier": "abc123def456..." }
}

{
  "id": "evt_01j9...", "type": "device.unregistered",
  "account_id": "acc_01j9...", "workspace_id": "ws_01j9...",
  "created_at": "2025-06-01T12:00:00.000Z",
  "data": { "pass_id": "pass_01j9...", "device_library_identifier": "abc123def456..." }
}

{
  "id": "evt_01j9...", "type": "batch.completed",
  "account_id": "acc_01j9...", "workspace_id": "ws_01j9...",
  "created_at": "2025-06-01T12:00:05.000Z",
  "data": {
    "job_id": "job_01j9...", "pass_count": 2,
    "completed_count": 2, "failed_count": 0,
    "results": [
      { "index": 0, "status": "ok", "id": "pass_01...", "error": null, "error_message": null },
      { "index": 1, "status": "ok", "id": "pass_02...", "error": null, "error_message": null }
    ]
  }
}