Walletpasses

Worked wallet-passes samples

The endpoint list below documents every operation’s parameters; this overlay sequences the round trip a wallet integration actually runs: issue a pass → read its state → push a content update → list and filter. Success envelopes are { data, meta }, error envelopes are { error, meta } — both shapes are covered in How to read a worked sample. Run the samples with a sandbox (dv_test_sk_*) key; nothing below needs Apple or Google credentials until a holder opens the save link. Every response carries meta.request_id. Quote it when you report a problem — support can trace the pass end-to-end in the ledger.

1. Issue a pass

POST /api/v1/wallet-passes/issue mints a pass. type is one of loyalty_card, coupon, or ticket; title is required; contact_id / external_id are optional correlation links. Brand fields are organization_name, background_color, foreground_color, and label_color (#RRGGBB). The barcode payload is barcode_message plus barcode_format — QR_CODE (default), PDF_417, AZTEC, or CODE_128. fields takes up to 20 {key, label, value} rows, and expires_at bounds the pass. The same body with the same idempotency_key replays the original pass instead of minting a duplicate.

curl -X POST "https://api.orbit.devotel.io/api/v1/wallet-passes/issue" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "loyalty_card",
  "title": "Northline Rewards",
  "subtitle": "Silver tier",
  "organization_name": "Northline Coffee",
  "contact_id": "cnt_8fb2d1b7c00c",
  "external_id": "order-10042",
  "barcode_message": "NLC-10042",
  "barcode_format": "QR_CODE",
  "fields": [{ "key": "points", "label": "Points", "value": "1,240" }],
  "background_color": "#0B2545",
  "foreground_color": "#FFFFFF",
  "idempotency_key": "enroll-order-10042"
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wallet-passes/issue",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "loyalty_card",
      title: "Northline Rewards",
      subtitle: "Silver tier",
      organization_name: "Northline Coffee",
      contact_id: "cnt_8fb2d1b7c00c",
      external_id: "order-10042",
      barcode_message: "NLC-10042",
      barcode_format: "QR_CODE",
      fields: [{ key: "points", label: "Points", value: "1,240" }],
      background_color: "#0B2545",
      foreground_color: "#FFFFFF",
      idempotency_key: "enroll-order-10042",
    }),
  },
);
console.log(await res.json());

import os, requests

r = requests.post(
    "https://api.orbit.devotel.io/api/v1/wallet-passes/issue",
    headers={
        "X-API-Key": os.environ["ORBIT_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "type": "loyalty_card",
        "title": "Northline Rewards",
        "subtitle": "Silver tier",
        "organization_name": "Northline Coffee",
        "contact_id": "cnt_8fb2d1b7c00c",
        "external_id": "order-10042",
        "barcode_message": "NLC-10042",
        "barcode_format": "QR_CODE",
        "fields": [{"key": "points", "label": "Points", "value": "1,240"}],
        "background_color": "#0B2545",
        "foreground_color": "#FFFFFF",
        "idempotency_key": "enroll-order-10042",
    },
)
print(r.json())

A first issue answers 201 (a replay of the same idempotency_key answers 200 with "replayed": true and the pass’s current state). platforms carries the per-platform install payloads:

201

{
  "data": {
    "id": "wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5",
    "type": "loyalty_card",
    "status": "active",
    "recipient_contact_id": "cnt_8fb2d1b7c00c",
    "external_id": "order-10042",
    "content": {
      "title": "Northline Rewards",
      "subtitle": "Silver tier",
      "organization_name": "Northline Coffee",
      "barcode_message": "NLC-10042",
      "barcode_format": "QR_CODE",
      "background_color": "#0B2545",
      "foreground_color": "#FFFFFF",
      "fields": [{ "key": "points", "label": "Points", "value": "1,240" }],
      "expires_at": null
    },
    "generation": 0,
    "idempotency_key": "enroll-order-10042",
    "replayed": false,
    "platforms": {
      "apple": {
        "configured": false,
        "reason": "apple_wallet_credentials_not_configured",
        "pass_json": null
      },
      "google": {
        "configured": true,
        "reason": null,
        "object": {
          "id": "3388000000012345678.wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5",
          "classId": "3388000000012345678.orbit_loyalty_card",
          "state": "ACTIVE"
        },
        "save_url": "https://pay.google.com/gp/v/save/eyJhbGciOiJ…"
      }
    },
    "issued_at": "2026-08-26T12:00:00.000Z",
    "updated_at": "2026-08-26T12:00:00.000Z",
    "voided_at": null
  },
  "meta": {
    "request_id": "req_wp_issue",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

platforms.apple.configured / platforms.google.configured tell you whether your account’s wallet credentials are connected (a platform that is not reports reason). Apple’s pass_json and Google’s object + save_url are what a client wraps into the wallet install flow; platform payloads are rebuilt on every read, so a save link starts working the moment credentials are connected — no re-issuance.

2. Read the pass back

GET /api/v1/wallet-passes/{id} returns the pass folded to its current state — freshly issued or updated, status reads active; after a void it reads voided, with voided_at and void_reason set. Prefer a re-read over the issue echo when you need the current save link or the latest state.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/wallet-passes/wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wallet-passes/wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

import os, requests

r = requests.get(
    "https://api.orbit.devotel.io/api/v1/wallet-passes/wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
print(r.json())

3. Push an update

POST /api/v1/wallet-passes/{id}/update is the patch: send only the content fields you are changing — a points fields re-render, a fresh subtitle, a coupon expires_at. Each accepted update bumps generation; the holder’s wallet refreshes from the platform push channel (Google’s object endpoint, Apple’s push notification), so the new balance shows without the holder re-saving the pass. An empty body is rejected at 422 with at least one field must be provided; updating a voided pass answers 409.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/wallet-passes/wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5/update" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "subtitle": "Silver tier — 1,250 points",
  "fields": [{ "key": "points", "label": "Points", "value": "1,250" }]
}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wallet-passes/wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5/update",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      subtitle: "Silver tier — 1,250 points",
      fields: [{ key: "points", label: "Points", value: "1,250" }],
    }),
  },
);
console.log(await res.json());

import os, requests

r = requests.post(
    "https://api.orbit.devotel.io/api/v1/wallet-passes/wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5/update",
    headers={
        "X-API-Key": os.environ["ORBIT_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "subtitle": "Silver tier — 1,250 points",
        "fields": [{"key": "points", "label": "Points", "value": "1,250"}],
    },
)
print(r.json())

200

{
  "data": {
    "id": "wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5",
    "type": "loyalty_card",
    "status": "active",
    "content": {
      "title": "Northline Rewards",
      "subtitle": "Silver tier — 1,250 points",
      "fields": [{ "key": "points", "label": "Points", "value": "1,250" }]
    },
    "generation": 1,
    "platforms": {
      "apple": {
        "configured": false,
        "reason": "apple_wallet_credentials_not_configured",
        "pass_json": null
      },
      "google": {
        "configured": true,
        "reason": null,
        "object": {
          "id": "3388000000012345678.wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5",
          "state": "ACTIVE"
        },
        "save_url": "https://pay.google.com/gp/v/save/eyJhbGciOiJ…"
      }
    },
    "updated_at": "2026-08-26T12:02:00.000Z"
  },
  "meta": {
    "request_id": "req_wp_update",
    "timestamp": "2026-08-26T12:02:00.000Z"
  }
}

Every accepted update also appends a wallet_pass.updated event to your tenant’s event ledger — the webhook your integration receives back confirming the push, carrying pass_id, only the changed content fields, and updated_by. Issue and void append wallet_pass.issued / wallet_pass.voided the same way; subscribe to them for your own pass-lifecycle automation, and see §6 for where the shapes live.

4. List and filter passes

GET /api/v1/wallet-passes pages passes newest-first with each row folded to its current state. Filter with type (loyalty_card|coupon|ticket), status (active|voided), or contact_id, and page with limit (max 200) and offset; meta.pagination.has_more says whether the next page exists.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/wallet-passes?type=loyalty_card&status=active&limit=20&offset=0" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wallet-passes?type=loyalty_card&status=active&limit=20&offset=0",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

import os, requests

r = requests.get(
    "https://api.orbit.devotel.io/api/v1/wallet-passes",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    params={"type": "loyalty_card", "status": "active", "limit": 20, "offset": 0},
)
print(r.json())

200

{
  "data": [
    {
      "id": "wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5",
      "type": "loyalty_card",
      "status": "active",
      "recipient_contact_id": "cnt_8fb2d1b7c00c",
      "external_id": "order-10042",
      "content": {
        "title": "Northline Rewards",
        "subtitle": "Silver tier — 1,250 points",
        "fields": [{ "key": "points", "label": "Points", "value": "1,250" }]
      },
      "generation": 1,
      "issued_at": "2026-08-26T12:00:00.000Z",
      "voided_at": null
    }
  ],
  "meta": {
    "request_id": "req_wp_list",
    "timestamp": "2026-08-26T12:03:00.000Z",
    "pagination": { "cursor": null, "has_more": false }
  }
}

5. Void a pass

POST /api/v1/wallet-passes/{id}/void is terminal: the pass flips to status: "voided", the wallet expires it at the next refresh, and any later update or void answers 409 (already_voided). Optional reason travels with the record as void_reason:

200

{
  "data": {
    "id": "wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5",
    "type": "loyalty_card",
    "status": "voided",
    "generation": 2,
    "voided_at": "2026-08-26T12:03:00.000Z",
    "void_reason": "customer requested cancellation"
  },
  "meta": {
    "request_id": "req_wp_void",
    "timestamp": "2026-08-26T12:03:00.000Z"
  }
}

6. Where the concepts and events live

Wallet passes channel — the channel concept: platform accounts, the save-link distribution pattern, and the ledger model behind issuance state.
Webhook event catalog — the delivery envelope your webhook endpoint receives; the wallet_pass.issued / wallet_pass.updated / wallet_pass.voided property shapes are the event payloads above, and the CDP endpoint page tails them live per tenant.

7. Errors worth branching on

Errors follow the { error, meta } envelope. The three failures every issuer hits: 422 — field validation. A color outside #RRGGBB, an unknown type or barcode_format, more than 20 fields, or an empty update body:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "background_color must be a #RRGGBB hex color.",
    "status": 422
  },
  "meta": {
    "request_id": "req_wp_err",
    "timestamp": "2026-08-26T12:04:00.000Z"
  }
}

404 — unknown pass. An id outside the wps_ + 32-hex format, or a pass never issued in this tenant:

404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Wallet pass wps_00000000000000000000000000000000 not found.",
    "status": 404
  },
  "meta": {
    "request_id": "req_wp_404",
    "timestamp": "2026-08-26T12:04:30.000Z"
  }
}

409 — lifecycle conflict. Update or void a pass that is already voided; issue a replacement pass instead:

409

{
  "error": {
    "code": "CONFLICT",
    "message": "Wallet pass wps_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3f5 is voided and cannot be updated.",
    "details": { "reason": "already_voided" },
    "status": 409
  },
  "meta": {
    "request_id": "req_wp_conflict",
    "timestamp": "2026-08-26T12:05:00.000Z"
  }
}

API Reference

All Endpoints

Worked wallet-passes samples

1. Issue a pass

2. Read the pass back

3. Push an update

4. List and filter passes

5. Void a pass

6. Where the concepts and events live

7. Errors worth branching on

​Worked wallet-passes samples

​1. Issue a pass

​2. Read the pass back

​3. Push an update

​4. List and filter passes

​5. Void a pass

​6. Where the concepts and events live

​7. Errors worth branching on

Worked wallet-passes samples

1. Issue a pass

2. Read the pass back

3. Push an update

4. List and filter passes

5. Void a pass

6. Where the concepts and events live

7. Errors worth branching on