REST and Agent API.

The APIs manage business product settings, not signed packages or a member's operational pass registry. They never return a Pass Type certificate, private key, password, private path, pass serial, authentication token, member data, package bytes, or download URL.

Item types

Use this closed set in {type}:

{id} must belong to the authenticated business. A missing, unsupported, soft-deleted prepaid, or foreign item returns not found so another business's records cannot be discovered.

Locale REST API

Partner authentication is required.

GET /api/{locale}/v1/partner/apple-wallet/{type}/{id}
PUT /api/{locale}/v1/partner/apple-wallet/{type}/{id}

GET returns the safe settings object directly. PUT accepts a partial idempotent representation and returns the resulting settings object directly.

{
  "enabled": true,
  "appearance": {
    "mode": "custom",
    "background_color": "#102033",
    "foreground_color": "#FFFFFF",
    "label_color": "#E9B949",
    "strip_focal_x": 50,
    "strip_focal_y": 40,
    "primary_locale": "en_US"
  }
}

At least one setting is required. Appearance fields are optional when the appearance object is omitted. Colors are #RRGGBB; focal points are integers from 0 through 100; locale must be one of the twelve supported locale codes.

Agent API

GET /api/agent/v1/partner/apple-wallet/{type}/{id}
PUT /api/agent/v1/partner/apple-wallet/{type}/{id}

The authenticated key also needs normal partner Agent API access. write:wallet is separate from write:passes: Wallet scope changes Apple presentation, while pass scope manages prepaid products and issued visits.

Agent success uses the standard envelope:

{
  "data": {
    "type": "loyalty",
    "item_id": "01234567-89ab-cdef-0123-456789abcdef",
    "enabled": true,
    "appearance": {
      "mode": "custom",
      "background_color": "#102033",
      "foreground_color": "#FFFFFF",
      "label_color": "#E9B949",
      "strip_focal_x": 50,
      "strip_focal_y": 40,
      "primary_locale": "en_US"
    },
    "assets": {
      "logo_source": "inherited",
      "strip_source": "apple_wallet_override"
    },
    "availability": {
      "infrastructure_configured": true,
      "entitled": true,
      "can_enable": true,
      "blocked_reason": null
    }
  },
  "meta": {
    "result": "updated"
  }
}

An identical PUT performs no model write and returns meta.result: "unchanged".

Enable and disable rules

Enabling requires both:

• effective Apple Wallet entitlement from the per-business override or plan;
• healthy installation signing configuration.

Disabling remains allowed when either is absent. This lets an integration reduce exposure safely after a downgrade or operator incident.

Agent errors use the normal machine envelope:

Administrator permission APIs

The existing administrator partner permission endpoints include apple_wallet_permission:

GET   /api/{locale}/v1/admin/partner/{partner}/permissions
PATCH /api/{locale}/v1/admin/partner/{partner}/permissions

GET   /api/agent/v1/admin/partners/{partner}
PATCH /api/agent/v1/admin/partners/{partner}/permissions

Set it to true to grant or false to revoke independently of the plan. Omitting it preserves the normal plan-derived default according to the surrounding partner-management contract.

Deliberate omissions

The API does not provide endpoints to download a signed member pass, upload signing credentials, inspect registry rows, read analytics events, reset issuer identity, or bypass the member/staff web flows. Credential custody and identity reset remain full-administrator dashboard operations. Member package download remains an authenticated, throttled browser action so the normal relationship and lifecycle gates run immediately before signing.