Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zupy.com/llms.txt

Use this file to discover all available pages before exploring further.

Zupy can deliver a customer’s loyalty card or coupon as an Apple Wallet / Google Wallet pass. As a partner you only tell Zupy which customer and which platform — Zupy generates the pass from the merchant’s existing card/coupon design and template.
Generation is reference-only. The integration cannot personalize the pass (no custom fields, colors, or templates). Zupy builds it from the data and wallet template the merchant already configured — exactly the same pass the customer would get from the program landing page.

​
How it works

Both the program landing page and the partner API use the same generator (PassGenerationService). The only difference is delivery:
FlowEndpointDelivery
Landing page (in-browser)downloads the .pkpass directlystreams the file / redirects to Google
Partner APIPOST /api/v2/wallet/passes/loyalty/returns a pass_url you hand to the customer
The pass_url is the same Apple .pkpass URL / Google Wallet save link the LoyaltyCard carries. The customer opens it to add the card to their wallet.

​
Generate a loyalty card pass

POST /api/v2/wallet/passes/loyalty/
Request body:
FieldTypeDescription
customer_idstringRequired. Customer KSUID (the LoyaltyUser).
platformstringRequired. apple or google.
curl -X POST "https://api.zupy.com/api/v2/wallet/passes/loyalty/" \
  -H "X-API-Key: zupy_pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "2awTHloSJX7kGGprFerOOsvABcd", "platform": "apple"}'
Response (201)
{
  "data": {
    "id": "2cxSLnqYLZ0nJJsuIhuSSvyFGij",
    "pass_url": "https://api.zupy.com/wallet/apple/2cxSLnqYLZ0nJJsuIhuSSvyFGij.pkpass",
    "platform": "apple",
    "created_at": "2026-05-25T18:00:00Z"
  },
  "meta": {}
}
Deliver pass_url to the customer (link, button, QR). Opening it adds the card to their wallet.

​
Generate a coupon pass

POST /api/v2/wallet/passes/coupons/
Same idea, plus the issued coupon to wrap:
FieldTypeDescription
customer_idstringRequired. Customer KSUID.
coupon_idstringRequired. Issued coupon KSUID (a RewardRedemption, see Coupon Lifecycle).
platformstringRequired. apple or google.

​
Check pass status

GET /api/v2/wallet/passes/{pass_id}/status/
Returns whether the pass was added/removed by the customer (useful for engagement metrics).

​
List a customer’s passes

GET /api/v2/wallet/passes/?customer_id={id}
Wallet endpoints require a read-write API key (they create passes). Read-only keys get 403 on the create endpoints.