Skip to main content

Introduction to SmartPass links

A Practical Guide to SmartPass Link Implementation

Written by Paul Tomes

Introduction

SmartPass Links provide a simple, scalable and cost-effective way to distribute personalised mobile passes for Apple Wallet and Google Wallet without requiring a complex API integration.

They allow you to generate secure, personalised links in advance, with each link containing the encrypted data needed to create a pass.

The key benefit is that passes are created on demand, rather than when the links are generated. This means you can prepare and distribute large numbers of SmartPass Links without immediately creating passes or incurring pass issuance charges.

SmartPass Links are particularly useful for marketing campaigns, loyalty programmes, coupons, memberships and other situations where you want to distribute passes to large audiences.

Please note: Event Tickets do no currently support SmartPass Links


What are SmartPass links?

A SmartPass Link is a unique URL containing encrypted data that PassKit uses to create a personalised mobile pass when the link is opened.

Unlike traditional pass issuance, generating a SmartPass Link does not immediately create a pass record in your PassKit account.

This distinction is important:

  • SmartPass Link: Contains the information required to create a pass. No pass record exists yet.

  • Issued pass: A pass record that has been created in PassKit and can subsequently be managed and updated.

You can generate SmartPass Links without increasing your issued pass volume. Pass creation and applicable billing occur when a new pass is successfully issued.

This makes SmartPass Links particularly efficient when you don't know how many recipients will actually request or install a pass.


How SmartPass Links Work

SmartPass links follow four main stages:

1. Prepare your data

Start by designing your pass template and preparing the information you want to include.

Depending on your use case, this might include customer names, membership numbers, coupon codes, offer details, expiry dates or other dynamic fields.

An External ID is optional. You may choose to use one when you want to reference passes using an identifier from your own system or take advantage of External ID uniqueness behaviour.

2. Generate SmartPass Links

PassKit encrypts the supplied data and generates a SmartPass Link for each record.

The link contains the information needed to create the pass, but no pass record has been created at this stage.

The resulting links can be distributed through your preferred channels, including email, SMS, websites and QR codes.

3. The recipient opens their link

When a recipient opens a SmartPass Link, PassKit decrypts the information and uses it to create the appropriate pass.

The recipient can then add the pass to Apple Wallet or Google Wallet.

If an External ID is used, PassKit can also apply its uniqueness behaviour to help prevent duplicate pass creation for the same identifier.

4. Manage and update the issued pass

Once the pass has been created, it becomes a record in your PassKit account.

You can then manage the pass and update supported dynamic fields using the PassKit portal or API.

Importantly, updating an issued pass does not change the original data encoded in the SmartPass Link.



What happens if my data changes or is incorrect?

A SmartPass Link contains encrypted data that is fixed when the link is generated.

What you can do if information changes depends on whether the pass has already been created.

If the SmartPass Link has not been opened

If the recipient has not opened their SmartPass Link and no pass has been created, there is no pass record in PassKit to update.

When the link is eventually opened, PassKit uses the original information encoded in that link.

If the data is incorrect or outdated, you should:

  1. Correct the information in your source data.

  2. Generate a new SmartPass Link containing the corrected values.

  3. Distribute the new link instead of the original.

Important: Updating your original CSV file, source system or pass template does not change the information encoded in previously generated SmartPass Links.

If an incorrect link has already been distributed, you cannot simply change its contents. You will need to consider how to replace that link for the intended recipient.

If the pass has already been created

Once the recipient has opened the SmartPass Link and the pass has been created, you can update supported dynamic fields through the PassKit portal or API.

For example, you might update:

  • A loyalty points balance

  • Offer details or expiry information

  • Customer information

  • A redemption code or barcode value stored in an updateable dynamic field

There are some important considerations.

External ID

The External ID is an optional, unique identifier used to reference a pass. It cannot be changed after the pass has been created.

If you expect a particular value to change in the future, consider storing it in a separate dynamic field rather than using the External ID directly.

Dynamic fields

Supported dynamic fields can be updated after pass creation, subject to the configuration and capabilities of your pass template.

Original SmartPass Link

Updating an issued pass does not change the data encoded in the original SmartPass Link.

Wallet updates

Updates to issued passes are not necessarily instantaneous. A customer's Apple Wallet or Google Wallet may temporarily display the previous information until the device receives the latest update.

For time-sensitive information, such as redemption codes, this is an important consideration.


Planning for future updates

If you anticipate needing to change certain values after issuance, consider separating permanent identifiers from updateable business information.

For example:

  • External ID (optional): A permanent identifier used to reference the pass in your own system and support uniqueness behaviour.

  • Redemption Code (dynamic field): A value used in the barcode that can be updated independently after pass creation.

You can configure the barcode payload and the human-readable text beneath it to use the same dynamic field.

This allows you to retain a consistent identifier while changing the redemption code when necessary.

Remember that dynamic fields can only be updated after the pass has been created. They do not make the original SmartPass Link editable.


Generating SmartPass links

CSV Upload

The PassKit portal provides a straightforward way to generate SmartPass Links from a CSV file.

This is ideal for smaller campaigns and bulk generation involving fewer than 10,000 rows.

Prepare your CSV containing the information required by your pass template, then upload it through the PassKit portal.

PassKit processes the data and generates a corresponding SmartPass Link for each record.

The resulting CSV contains your original data together with an additional column containing the generated SmartPass Link.

You can then use these links in your preferred distribution platform.

Command-Line Tool

For larger datasets, the SmartPass Command-Line Tool provides a faster method of generating links.

It is designed for high-volume processing and can generate up to one million SmartPass Links in under 10 seconds under suitable conditions.

This approach is useful when working with very large CSV files or when incorporating SmartPass Link generation into an existing data-processing workflow.

API

SmartPass Links can also be generated programmatically using the PassKit API.

This is suitable for developers who want to integrate link generation into their own applications, customer engagement platforms or automated workflows.

Note: Generating SmartPass Links through the API is different from issuing passes directly through the PassKit API.

With SmartPass Links, pass creation is deferred until the link is opened. With direct API issuance, the pass record is created when the API request is processed successfully.


Before distributing your SmartPass Links

SmartPass Links are designed to make large-scale pass distribution efficient. However, because each link contains the data used to create a pass, validating your configuration and source information before distribution is essential.

We recommend completing the following checks before launching a campaign.

Pre-launch checklist

  • Validate your source data. Check for incorrect, missing or outdated values, including customer information, barcode contents, offer details and expiry dates.

  • Check External IDs, if used. Ensure identifiers are unique where required and correctly associated with their intended recipients.

  • Verify dynamic field mappings. Confirm that each field in your source data maps to the correct field in your pass template.

  • Check your barcode configuration. Confirm that the barcode payload and any human-readable text contain the intended values.

  • Generate test SmartPass Links. Create a small sample using representative data, including relevant edge cases.

  • Open and inspect the test passes. Verify that Apple Wallet and Google Wallet display the expected information.

  • Test redemption and expiry behaviour. Ensure passes work as expected with your redemption systems and campaign rules.

  • Test subsequent updates, if required. Confirm that supported dynamic fields can be updated correctly after pass creation.

  • Review your final distribution data. Ensure the SmartPass Links being sent to recipients were generated from the validated dataset.

Our recommendation: Always test the complete process using a small number of passes before distributing SmartPass Links to a larger audience.

Once links have been distributed, correcting mistakes can become more complicated, particularly when some recipients have already created their passes while others have not.

Thorough testing helps prevent issues during live campaigns and ensures a better experience for your customers.


Secure storage and distribution

PassKit does not store the SmartPass Links you generate.

Instead, the generated links are returned to you, typically as part of a CSV file containing your source data and the corresponding SmartPass URLs.

You are responsible for securely storing and distributing SmartPass Links

Although the personalised information within each SmartPass Link is encrypted, the link itself can be used to initiate pass creation.

For this reason, SmartPass Links should be treated as sensitive distribution assets and shared only with their intended recipients.

You can distribute them through channels such as email, SMS, websites, QR codes or your own customer engagement platform.

PassKit securely manages the encryption keys required to decrypt the information when a SmartPass Link is opened.

This approach allows PassKit to create passes on demand without needing to maintain a database of all the links you have generated.

It also gives you flexibility over how and when you distribute passes to your customers.
​


Changing your pass template after generating SmartPass Links

SmartPass Links are generated using the data and field configuration available at the time of generation.

If you subsequently change your pass template, previously generated links will not automatically contain any newly required information.

What can happen?

For example, imagine you generate SmartPass Links containing a customer's first name.

Later, you update your pass template to include additional dynamic fields such as last name or mobile number.

The original SmartPass Links do not contain values for those additional fields.

Depending on the configuration, this may result in:

  • Missing information: The pass may be created, but newly introduced fields may be blank.

  • Pass creation failure: If the updated template requires information that is not present in the original link, pass creation may fail.

  • Unexpected results: The information displayed may not match the intended customer experience.

Best practices when changing templates

Plan your template before generating links

Define the fields you expect to use before generating and distributing SmartPass Links, particularly those required for barcode generation, redemption or other essential functionality.

Review the impact of changes

Before modifying a live template, consider whether previously generated SmartPass Links may still be in circulation.

Regenerate links where necessary

If the links have not yet been distributed, you can regenerate them using the updated template and source data.

If links have already been distributed, you will need to consider how those changes affect recipients who have not yet opened their links.

Consider separate templates or projects

For substantial changes, creating a separate template or project may be preferable to modifying a live campaign that already has SmartPass Links in circulation.

Test existing and new links

Whenever possible, test both previously generated links and newly generated links after making template changes.

This helps identify compatibility issues before they affect customers.


Key takeaway

SmartPass Links offer an efficient and cost-effective way to distribute personalised mobile passes at scale.

The most important principles to remember are:

  • A SmartPass Link is not an issued pass. It contains encrypted data used to create a pass when opened.

  • The data encoded in a SmartPass Link is fixed. If that data is incorrect, a new link must be generated.

  • Issued passes can be updated. Once created, supported dynamic fields can be managed through the PassKit portal or API.

  • PassKit does not store your generated SmartPass Links. You are responsible for securely storing and distributing them.

  • Testing is essential. Always validate your source data, configuration and complete customer experience before launching a campaign.

By understanding how SmartPass Links work and following these best practices, you can distribute passes confidently while reducing the risk of errors and unexpected behaviour.

Did this answer your question?