Wallet Passes

Query wallet pass templates, list wallet passes for customers, verify a scanned pass, and send push notifications to wallet pass holders.

List Templates

Retrieve wallet pass templates for a specific shop.

GET /v1/management/wallet-passes/templates

string

required

The shop identifier

Required permission: wallet_pass_template:read

Example Request

curl -X GET "https://api.rxscale.com/v1/management/wallet-passes/templates?shop_identifier=my-shop" \
  -H "X-API-Key: your-api-key-here"

Response

{
  "data": [
    {
      "uid": "wpt-abc123",
      "display_name": "Loyalty Card",
      "pass_type": "generic",
      "shop_identifier": "my-shop"
    }
  ],
  "total": 1
}

List Wallet Passes

Retrieve wallet passes for a specific shop customer and shop combination.

GET /v1/management/wallet-passes

string

required

The shop customer ID

string

required

The shop identifier

string

Optional template UID to filter by

Required permission: wallet_pass:read

Example Request

curl -X GET "https://api.rxscale.com/v1/management/wallet-passes?shop_customer_id=cust-123&shop_identifier=my-shop" \
  -H "X-API-Key: your-api-key-here"

Response

{
  "data": [
    {
      "uid": "wp-abc123",
      "wallet_pass_template_uid": "wpt-abc123",
      "wallet_pass_template": {
        "uid": "wpt-abc123",
        "display_name": "Patient Pass",
        "external_id": "passcreator-template-id",
        "meta_data": {"template_type": "prescription", "version": "1.0"},
        "created_at": 1712100000,
        "updated_at": 1712100000,
        "deleted_at": null
      },
      "external_id": "passcreator-pass-id",
      "serial_number": "SER-000123",
      "ios_download_url": "https://pass.example/ios/wp-abc123",
      "android_download_url": "https://pass.example/android/wp-abc123",
      "patient_profile_uid": "pat-abc123",
      "created_at": 1712200000,
      "updated_at": 1712200000,
      "deleted_at": null
    }
  ],
  "total": 1
}

total is the number of passes in data — this endpoint returns every matching pass in one response and is not paginated, so it carries neither totalRegistries nor totalPages.

The Wallet Pass Object

Field	Type	Description
`uid`	string	Wallet pass UID. This is the value encoded in the pass barcode — treat it as a credential
`wallet_pass_template_uid`	string	UID of the template the pass was issued from
`wallet_pass_template`	object	The template, inlined
`external_id`	string \| null	Identifier of the pass at the wallet pass provider
`serial_number`	string \| null	Serial number of the issued pass
`ios_download_url`	string \| null	Link the patient uses to add the pass to Apple Wallet
`android_download_url`	string \| null	Link the patient uses to add the pass to Google Wallet
`patient_profile_uid`	string	UID of the patient the pass belongs to
`created_at`	integer	Creation timestamp (Unix seconds)
`updated_at`	integer	Last update timestamp (Unix seconds)
`deleted_at`	integer \| null	Deletion timestamp (Unix seconds), or `null` while the pass is active

Create a Wallet Pass

POST /v1/management/wallet-passes

Issues a pass for a patient from one of your templates. The patient is identified by your own shop_customer_id together with the shop_identifier, so you never need to resolve an RxScale patient UID first. Required permission: wallet_pass:write

Request Body

string

required

UID of the template to issue from. Get it from GET /wallet-passes/templates.

string

required

Your customer identifier for the patient

string

required

The shop the customer belongs to

Example Request

curl -X POST "https://api.rxscale.com/v1/management/wallet-passes" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_pass_template_uid": "wpt-abc123",
    "shop_customer_id": "cust-123",
    "shop_identifier": "my-shop"
  }'

Response

Returns the wallet pass object.

The status code tells you whether a pass was created or reused. This endpoint is idempotent per patient and template: 201 means a new pass was issued, 200 means the patient already had a pass for that template and it was refreshed and returned. Calling it twice will not give the patient two passes.

{
  "uid": "wp-abc123",
  "wallet_pass_template_uid": "wpt-abc123",
  "external_id": "passcreator-pass-id",
  "serial_number": "SER-000123",
  "ios_download_url": "https://pass.example/ios/wp-abc123",
  "android_download_url": "https://pass.example/android/wp-abc123",
  "patient_profile_uid": "pat-abc123",
  "created_at": 1712200000,
  "updated_at": 1712200000,
  "deleted_at": null
}

Hand ios_download_url / android_download_url to the patient to add the pass to their wallet.

Error Responses

Status Code	Description
`400`	Missing or invalid fields, or the template requires a signed prescription and this patient has none
`403`	Missing `wallet_pass:write` permission
`404`	Template, shop, or patient not found, or belongs to another organisation

A template that requires a signed prescription returns a specific message, so you can distinguish it from a malformed request:

{
  "error": "The wallet pass template requires a signed prescription, but this patient has none."
}

Get a Wallet Pass

GET /v1/management/wallet-passes/{wallet_pass_uid}

Loads a single pass by UID. Use this to re-read the download links, or to check whether a pass is still active (deleted_at is null). Required permission: wallet_pass:read

string

required

The wallet pass UID

Example Request

curl -X GET "https://api.rxscale.com/v1/management/wallet-passes/wp-abc123" \
  -H "X-API-Key: your-api-key-here"

Response

Returns the wallet pass object.

Error Responses

Status Code	Description
`403`	Missing `wallet_pass:read` permission
`404`	Pass not found, or it belongs to another organisation

Delete a Wallet Pass

DELETE /v1/management/wallet-passes/{wallet_pass_uid}

Revokes a pass. The pass is soft-deleted: the record is kept and deleted_at is set, so a scan of a revoked pass still resolves — POST /wallet-passes/verify answers "valid": false with "status": "revoked" rather than a 404. Required permission: wallet_pass:write

string

required

The wallet pass UID

Example Request

curl -X DELETE "https://api.rxscale.com/v1/management/wallet-passes/wp-abc123" \
  -H "X-API-Key: your-api-key-here"

Response

204 No Content with an empty body.

Error Responses

Status Code	Description
`403`	Missing `wallet_pass:write` permission
`404`	Pass not found, or it belongs to another organisation

Verify a Scanned Pass

Resolve a scanned Patient Pass to shop-scoped identity handles. Requires an API key with the wallet_pass:verify permission.

POST /v1/management/wallet-passes/verify

Required permission: wallet_pass:verify

Request Body

string

required

The value encoded in the pass barcode. Treat it as a credential and send it in the body, never in a URL.

Example Request

curl -X POST "https://api.rxscale.com/v1/management/wallet-passes/verify" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"wallet_pass_uid": "3f9a1c2e-7b04-4c11-9f3d-2a8e5b6c0d17"}'

Response (200)

{
  "valid": true,
  "status": "active",
  "wallet_pass_uid": "3f9a1c2e-7b04-4c11-9f3d-2a8e5b6c0d17",
  "patient_profile_uid": "b21d4f8a-5c33-4e90-8a72-1f6b9d0c4e55",
  "shop_customer_id": "cust-123"
}

A revoked pass returns "valid": false with "status": "revoked". shop_customer_id is absent for passes issued before the shop customer requirement.

Treat the wallet_pass_uid as a credential — anyone holding it can resolve the patient behind the pass. Send it in the request body, never in a URL, and do not write it to logs.

This endpoint returns identity handles only. Load the patient’s details with GET /v1/management/patients.

Error Responses

Status Code	Description
`400`	Missing `wallet_pass_uid`
`403`	Missing `wallet_pass:verify` permission
`404`	Unknown pass, or a pass belonging to another organisation

Send Push Notifications

Send push notifications to one or more wallet pass holders. Accepts a batch of notifications.

POST /v1/management/wallet-passes/push-notifications

Required permission: wallet_pass_push_notification:write

Request Body

The request body is a JSON array of notification objects.

[
  {
    "wallet_pass_uid": "wp-abc123",
    "message": "Your prescription is ready for pickup!"
  },
  {
    "wallet_pass_uid": "wp-def456",
    "message": "Hello {first_name}, your order has been shipped."
  }
]

Field	Type	Required	Description
`wallet_pass_uid`	string	Yes	UID of the wallet pass to send the notification to
`message`	string	Yes	Push notification message text (supports `{field}` placeholders)

Example Request

curl -X POST "https://api.rxscale.com/v1/management/wallet-passes/push-notifications" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "wallet_pass_uid": "wp-abc123",
      "message": "Your prescription is ready for pickup!"
    }
  ]'

Response (201 Created)

{
  "data": [
    {
      "uid": "wpn-abc123",
      "wallet_pass_uid": "wp-abc123",
      "message": "Your prescription is ready for pickup!",
      "status": "queued"
    }
  ],
  "total": 1
}

Error Responses

Status Code	Description
`400`	Invalid body format, empty array, validation error, or wallet pass not found
`403`	Missing `wallet_pass_push_notification:write` permission

​Wallet Passes

​List Templates

​Example Request

​Response

​List Wallet Passes

​Example Request

​Response

​The Wallet Pass Object

​Create a Wallet Pass

​Request Body

​Example Request

​Response

​Error Responses

​Get a Wallet Pass

​Example Request

​Response

​Error Responses

​Delete a Wallet Pass

​Example Request

​Response

​Error Responses

​Verify a Scanned Pass

​Request Body

​Example Request

​Response (200)

​Error Responses

​Send Push Notifications

​Request Body

​Example Request

​Response (201 Created)

​Error Responses

Wallet Passes

List Templates

Example Request

Response

List Wallet Passes

Example Request

Response

The Wallet Pass Object

Create a Wallet Pass

Request Body

Example Request

Response

Error Responses

Get a Wallet Pass

Example Request

Response

Error Responses

Delete a Wallet Pass

Example Request

Response

Error Responses

Verify a Scanned Pass

Request Body

Example Request

Response (200)

Error Responses

Send Push Notifications

Request Body

Example Request

Response (201 Created)

Error Responses