This guide is for developers and product teams who want to build scalable, branded digital loyalty cards using a modern and flexible loyalty program API. With Badge, you get developer-grade tools that save time and simplify the process. You can issue loyalty cards to Apple Wallet and Google Wallet, keep them updated in real time, and trigger mobile wallet push notifications. Badge works with your existing stack so you can launch quickly without rebuilding your infrastructure.

In this guide, you will learn how to:

• Create a dynamic loyalty card template

• Connect your data using the userPassUpsert API

• Trigger real-time mobile wallet notifications to keep users engaged

Whether you are building your first digital loyalty card or replacing an outdated system, Badge gives you the tools to deliver a smarter mobile wallet loyalty program with speed, scale, and simplicity.

Step 1: Creating a Digital Loyalty Card Template With Badge

Every mobile wallet loyalty card starts with a pass template. This controls how your card looks, what data it shows, and how it behaves in Apple Wallet or Google Wallet. Once you publish it, Badge gives you a passTemplateId that you will use to issue cards through the API or no-code dashboard.

Templates are the foundation of all wallet passes, whether you are creating loyalty cards, event tickets, or digital membership cards. Each one comes with customizable fields that can show static content or update in real time through your connected data source.

The easiest way to get started is with the Badge Pass Template Editor. It lets you build your card visually by choosing the layout, colors, barcode format, and data fields. No code or design tools required.

Fields You Can Customize in the Template

Core Visual and Layout Fields

• description (Required): The user-facing name of the pass. This should end with a descriptor like “Pass,” “Card,” or “Ticket.” (Note: does not support dynamic values.)

• logoUri (Required): URL to your brand logo shown at the top of the pass.

• iconUri (Optional): Defaults to logoUri if not set.

• coverImageUri: A branded image shown above the barcode, resized for consistency across platforms.

• alternateCoverImageUri (Optional): Used for Google Wallet to meet stricter size or format requirements (supports webp or gif for animation).

• backgroundColorHex (Required): Sets the background color of the pass.

• textColorHex (Required): Sets the text color.
  (Note: background and text color fields do not support dynamic values.)

Content and Dynamic Data Fields

• heading: Optional title shown prominently on the pass.

• headerField: Used for key details like membership name or ID.

• secondaryFields: Array of field objects. Common uses include:

  • Cardholder name via ⚡ Custom Attribute

  • Loyalty tier or status

  • Point or credit balance

• barcodeType: Barcode format (e.g., QR, Code128).
  (Note: barcode is static and cannot be changed dynamically.)

• barcodeData: Dynamic data source for the barcode, often used to link the pass to your system (e.g., user ID, redemption token).

• barcodeText: Optional text shown below the barcode.

Additional Fields

• backFields: Array of objects for supporting content like terms, disclaimers, or support contact. These can be personalized per user.

• locationMessages: Trigger messages based on user location—ideal for in-store offers or visit-based rewards.

• expiresAt: ISO 8601 timestamp or dynamic value for expiration.

• webAppLinkUri: For linking to a web app (Google Wallet only).

• androidPackageName, androidLinkDisplayText: Android-specific launch behaviors.

• iosStoredIdentifiers, iosLaunchUri: iOS app linking support.

Custom Attributes are how you personalize passes at scale. Use them to update key fields like name, balance, and tier in real time. You can set values when the pass is issued or update them anytime using the Badge API.

The back of the pass can include optional details like terms, customer support info, or disclaimers. These fields can also be customized per user using Custom Attributes.

Suzanne notes: can we add details in the second set of bullets (under "Additional Fields") for Value Added Opportunities? Details are here: https://docs.trybadge.com/reference/valueaddedopportunityupsert (and more details here: https://coda.io/d/Value-Add-Opportunities-Rebrand_dShY6dgDd2E/Value-Add-Opportunities-Rebrand_suS-hQBW)

Step 2: Connecting Your Loyalty Data to the Card

Once your template is ready, it is time to bring it to life with real data. This step links each pass to member-specific information like name, tier, and point balance. That is where Custom Attributes come in.

Each Custom Attribute in your template pulls from your system of record, whether that is a CRM, a database, or a custom backend. This ensures every card is personalized with the right data at the time of issue and stays current as that data changes.

For Testing and Low Volume: Use CSV Import

If you are testing or running a smaller-scale loyalty program, the CSV Import tool is the fastest way to get started. Just upload a spreadsheet with user-specific data that maps to the fields in your pass template. It is a simple way to validate how your pass looks and behaves before going live.

For Real-Time and Scalable Programs: Use the Badge API

For high-volume use cases, the Badge API gives you full control over issuing, updating, and managing loyalty passes in real time.

The core method you'll use is the userPassUpsert endpoint, which lets you:

• Issue a pass when a new loyalty member is created in your system, using the correct Custom Attribute values (e.g., name, tier, points).

• Retrieve the Pass Download Link to embed in:

  • Post-sign-up confirmation pages

  • Loyalty program emails

  • Mobile app or in-app messaging flows

• Update a pass when something changes (e.g., updated point balance or upgraded tier).

The userPassUpsert request ensures each user’s pass reflects the most up-to-date information—without needing to reissue the pass.

Need a Custom Integration?

For enterprise programs with more complex infrastructure, Badge offers custom integrations. These connect directly to your data pipeline to automate every step, from syncing loyalty data to generating passes and sending notifications. Our team works with you to tailor the flow to your stack and streamline your customer loyalty programs.

Step 3: Send Real-Time Push Notifications to Engage Loyalty Members

When a loyalty card is saved to Apple Wallet or Google Wallet, it becomes a direct engagement channel. You can reach users through push notifications delivered straight to their lock screens. These are ideal for promoting offers, reactivating inactive members, or celebrating milestones like tier upgrades.

Wallet notifications are especially powerful because they are opt-in by default. The moment someone installs a pass, they are automatically subscribed to receive updates. There are no extra prompts or permissions, which leads to much higher engagement than email or SMS.

How Push Notifications Work with Badge

Once a pass template is live and installed by users, you can trigger push notifications directly to their devices using the Badge API. These notifications appear on the lock screen through Apple Wallet or Google Wallet, making them highly visible and actionable.

Badge provides two ways to send notifications:

1. Send to Individual Users

Use the /pass.sendPushNotification endpoint to send a push message to a single pass instance. This is useful for transactional or behavior-based updates.

Parameters include:

• passId: The unique ID of the installed pass

• message: The content of the notification (required)

• launchUrl: Optional, opens a web or app experience when tapped

2. Send to a Segment (Batch Notification)

Use the /notification.batch.create endpoint to send a message to all passes issued from a specific template. You can filter recipients using custom attribute logic.

You can:

• Target all users of a specific templateId

• Apply filters using custom attributes, such as tier equals “Gold” or last_scan is more than 30 days ago

• Set a scheduledAt value to send the notification at a future time, such as three days before a points expiration or a promotion

3. Monitor Notification Status

Use the /notifications.list endpoint to retrieve a list of previously sent notifications.

This returns details such as:

• Message content

• Timestamp

• Status (e.g., scheduled, sent, failed)

• Targeting logic

Push notifications in Badge are tied directly to the wallet pass and do not require additional app permissions. They are opt-in by default and are delivered through the native wallet infrastructure on iOS and Android. This gives you a direct, low-friction channel to reach users without needing third-party push tools.

Build Smarter Loyalty Programs with Badge

Badge gives your team the tools to launch and scale a modern loyalty program without the overhead. Build personalized digital loyalty cards for Apple Wallet and Google Wallet using flexible APIs, real-time updates, and seamless data integrations.

No waiting on long dev cycles. No rebuilding your stack. Just clean, scalable infrastructure that works out of the box.

Ready to build your next loyalty program?

👉 Talk to our team and see how simple it can be to launch scalable, branded digital loyalty cards with Badge.

Badge Frequently Asked Questions (FAQs)

What is a loyalty program API?

A loyalty program API is a set of tools that allows developers to create, issue, and manage digital loyalty cards through code. With the Badge API, you can automate pass creation, connect real-time customer data, and trigger mobile wallet notifications without relying on manual workflows or multiple systems.

Can I create digital loyalty cards for Apple Wallet and Google Wallet?

Yes. Badge makes it easy to design and launch digital loyalty cards for both Apple Wallet and Google Wallet from a single platform. You can fully customize each card’s branding, layout, and barcode, then distribute them using smart install links in emails, SMS, websites, and mobile apps.

How do QR code loyalty programs work with Badge?

Badge supports QR code loyalty programs by letting you assign a unique QR code to each digital loyalty card. These codes can be personalized using Custom Attributes and scanned for redemptions, check-ins, or rewards. All scan activity can be tracked through the Badge platform or API in real time.

How does Badge update digital loyalty cards in real time?

Once a loyalty card is saved to a user’s mobile wallet, Badge lets you update the content instantly through the API. You can change point balances, upgrade tiers, or modify visuals without asking users to download a new pass. These updates appear automatically on their device.

Can I personalize loyalty cards for each user?

Yes. With Badge, every loyalty card can be personalized using Custom Attributes. You can show the user’s name, membership tier, balance, and more. These attributes can be pulled from your CRM, database, or backend system and applied during pass creation or update.

Is Badge suitable for large-scale customer loyalty programs?

Absolutely. Badge is built to handle high-volume programs with thousands or millions of users. You can issue and manage passes at scale, connect your own data systems, and automate engagement with wallet-native notifications. Whether you’re running a national brand or regional campaign, Badge supports your growth.

What’s the fastest way to launch a mobile wallet loyalty program?

The fastest way is to use Badge’s no-code tools to create your pass, upload your loyalty data using a CSV or connect via API, then share the pass link across your existing channels. Customers can install their loyalty card in one tap. No app downloads required.

How do I add loyalty cards to Apple Wallet?

With Badge, adding a loyalty card to Apple Wallet is simple for both marketers and users. Once a digital loyalty card is created and issued, each user receives a unique Pass Download Link. This link can be shared through email, SMS, app notifications, or web pages.

When a user taps the link on their iPhone, the Apple Wallet pass opens instantly with the option to “Add to Apple Wallet.” With just one tap, the loyalty card is saved and ready to use.

There is no need to download an app or go through extra steps. Badge handles pass compatibility, formatting, and delivery automatically, so you can offer a seamless mobile wallet experience out of the box.