Update Wallet Pass

Skill: Update Wallet Pass

Overview

This skill enables agents to update fields on a wallet pass using an external ID. You can update field values, labels, headers, locations, beacons, and other pass properties. Only include the fields you want to update in the request.

API Endpoint

Method: PUT
Path: /pass/template/{templateId}/id/{passExternalId}
Base URL:

• US: https://wallet-api.urbanairship.com/v1
• EU: https://wallet-api.asnapieu.com/v1

Path: /pass/template/{templateId}/id/{passExternalId}

Authentication

Preferred: OAuth 2.0 Bearer token
Fallback: Basic Auth (project_key:project_secret) for environments not using OAuth

OAuth (recommended)

There are two ways to authenticate to the token endpoint. Both return a Bearer token used in the same way. Choose based on which credentials were generated when creating the OAuth client in Settings > OAuth.

Token endpoints:

• US: https://oauth2.asnapius.com/token
• EU: https://oauth2.asnapieu.com/token

In both flows, use the returned access_token as Authorization: Bearer <access_token>. Tokens expire in 1 hour (expires_in: 3600).

JWT assertion (private_key_jwt)

The more secure option. Requires: Client ID, private key, and app key.

• Client ID — identifies the OAuth client (Settings > OAuth)
• Private key — signs the JWT assertion (Settings > OAuth, generated at credential creation)
• App key — 22-character key identifying the Wallet project (Settings > API); goes in the sub claim as app:<app_key>

Build a signed JWT with these claims (ES384 algorithm):

curl -s -X POST "https://oauth2.asnapius.com/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "assertion=<signed_jwt>"

Do not include an Authorization header when using this flow.

Client secret (client_secret_basic)

Simpler but less secure. Requires Allow Basic Auth to be enabled when the OAuth credentials were created — this generates a Client Secret. Requires: Client ID, Client Secret, and app key.

curl -s -X POST "https://oauth2.asnapius.com/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(client_id:client_secret)>" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "sub=app:<app_key>" \
  --data-urlencode "scope=wpas"

Note: sub and scope are body parameters in this flow, not JWT claims.

Basic Auth (fallback)

If OAuth is not configured, use the Wallet project credentials: Authorization: Basic <base64(project_key:project_secret)>

These are found in the Wallet project dashboard under Settings > API. They are not the same as Airship Engage app key/master secret.

Request Headers

Api-Revision: 1.2
Accept: application/json
Content-Type: application/json
Authorization: Bearer <access_token>

If using fallback auth: Authorization: Basic <base64(project_key:project_secret)>

Request Schema

Provide only the fields you want to update. The request body supports partial updates.

Update Pass Request

{
  "fields": {
    "fieldName": {
      "value": "New Value",
      "label": "Field Label",
      "changeMessage": "Your pass has been updated"
    }
  },
  "headers": {
    "headerName": {
      "value": "Header Value",
      "label": "Header Label",
      "changeMessage": "Header updated"
    }
  },
  "locations": [
    {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "relevantText": "Near San Francisco"
    }
  ],
  "beacons": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "relevantText": "Near beacon"
    }
  ]
}

Required Path Parameters

• templateId: The ID of the template the pass was created from (string)
• passExternalId: The external ID assigned to the pass (string)

Optional Request Fields

Fields Object (fields):

• Object mapping field names to field update objects
• Each field update object contains:
  • value (required): string - The new field value
  • label (optional): string - The field label/title
  • changeMessage (optional): string - Message shown when field updates (use %@ for variables)

Headers Object (headers):

• Object mapping header names to header update objects
• Same structure as fields (value, label, changeMessage)

Locations Array (locations):

• Array of location objects (replaces all existing locations)
• Each location requires:
  • latitude: number
  • longitude: number
  • relevantText: string (optional) - Text shown when near location

Beacons Array (beacons):

• Array of beacon objects (Apple Wallet only, up to 10 beacons)
• Each beacon requires:
  • uuid: string - UUID of the iBeacon
  • major: integer - Major identifier of the beacon
  • minor: integer - Minor identifier of the beacon
  • relevantText: string - Text shown when near beacon

Semantics Object (semantics):

• Apple Wallet boarding pass semantics (object)

Universal Links Object (universalLinks):

• Object containing universal link key-value pairs

Examples

See example files in the examples/ directory:

• update-pass-fields.json - Update field values and labels
• update-pass-locations.json - Update pass locations

Example 1: Update Field Values

PUT /pass/template/123/id/pass-abc-123
{
  "fields": {
    "balance": {
      "value": "$150.00",
      "changeMessage": "Your balance has been updated to %@"
    },
    "memberName": {
      "value": "John Doe",
      "label": "Member"
    }
  }
}

Example 2: Update Locations

PUT /pass/template/123/id/pass-abc-123
{
  "locations": [
    {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "relevantText": "Near Store Location"
    }
  ]
}

Response Schema

Success Response (200 OK)

{
  "ticketId": 12345
}

The ticketId can be used to track the update operation status via the tickets API.

Error Handling

400 Bad Request

Occurs when:

• Request body is malformed
• Invalid field values
• Missing required fields in nested objects

404 Not Found

Occurs when:

• Template ID does not exist
• Pass with the specified external ID does not exist

Best Practices

1. Partial Updates: Only include fields you want to update - you don't need to send the entire pass object
2. Locations Replacement: Updating locations replaces all existing locations - include all locations you want to keep
3. Change Messages: Use changeMessage to notify pass holders when important fields update
4. Field Labels: Only provide label if you want to override the template's default label
5. Beacon Limits: Apple Wallet supports up to 10 beacons per pass

Use Cases

1. Update Pass Values: Update field values like balance, points, or status
2. Update Locations: Add or replace pass locations for location-based notifications
3. Update Beacons: Add or update iBeacons for proximity-based pass relevance
4. Update Headers: Modify header information displayed on the pass
5. Notify Users: Use change messages to notify users when pass information changes

Workflows Using This Skill

• Purchase-to-Pass Update: POS system emits purchase events → RTDS listener processes events → Updates wallet pass points
  • See Workflow Guide

Related Skills

None currently. This is the first wallet skill.

Additional Resources

• Wallet API Reference
• Wallet OpenAPI Specification
• Update Passes Guide