Wallet Batch Update

Any dynamic or personalized data on an installed wallet item can be updated via API or batch file. This allows you to perform bulk changes such as marking passes as redeemed, updating loyalty points, and more.

❗️

Important

A wallet batch update cannot be uploaded via the platform like the other import files. Instead, it must be updated using Secure File Transfer Protocol.

File Specifications

File Name

[file name].wallet_update

File Format

The contents of the file should be plain text separated by commas or another delimiter.

File Size

If you are uploading via the platform, we recommend files are less than 5MB, which is usually about 100,000 rows of data.

If you are uploading files via SFTP, there is no limit; however, larger files may take more time to upload.

First Class Fields

See the First Class Fields page to get more information on how first-class fields work.

Headers

You can include the following header in your subscriber import. Using headers is optional.

HeaderRequiredDescription
FieldsNoThis is a comma separated list of the fields that will be in the body of the text file. If omitted, then the first row of the body must contain the field names, with the same delimiter as the body.
DelimiterNoThe character used to delimit the columns. Defaults to a comma ",".
Campaign-TokenNo if campaign-token is included on each row.If not specified here, it must be specified in every row. Any value that is specified in the row takes precedence over the header value.

A campaign-token can be a single campaign token or a comma-separated list of tokens. If a list of tokens is provided, wallet will update the matching items found in all the specified campaigns.

Body

The file body can contain the following fields as data. All field names must be lowercase.

Field NameData TypeDescription
uuidStringThe pass unique identifier.
campaign_tokenStringThis token identifies the campaign that the passes to be updated belong to. Any value specified in a body row take precedence over the header value.
expiration_dateStringIf you’re using the bulk update to mark the passes as expired, set the expirationdate field to a value in the past. If you’re trying to mark passes as redeemed, this functionality can also be used by setting the expiration date to the date on which the pass was utilized.

- On iOS: the barcode image will grey out and text will appear beneath it that reads "this pass has expired"
- On Android: the pass will be moved into the expired passes section.This should be a date/time string that can be parsed by Ruby's Time.parse method (ISO8601 format). This can be nil/empty._Example: YYYY-MM-DD for date or YYYY-MM-DDTHH:MM:SS+0:00 for date/time.
token_field
(example: available_reward)
StringDynamic fields in wallet are known as “tokens,” which can pass dynamic content to a user’s wallet pass.

Notes:

- Any fields that are specified will be updated with the new values
- Any fields whose value is set to Null will be removed from the wallet item
- If a cell under a specified token field column is left blank, the value in the wallet item will be removed
- Any token field names that are not included in the column headers will be ignored and any existing values will remainIn the .csv file, the tokenfield header names are case sensitive and should match the case used in the Vibes platform. For example, if on the wallet pass template there is a token_field called _Rewards_Number, the header name in the batch file with the changes to this field shouldn't read rewardsnumber, it should match the upper case original: _Rewards_Number.
IMAGE_CODEStringIf additional strip images have been uploaded in the Vibes platform for a particular campaign, you can change the strip image on the pass by placing the new image file name (without the file type extension) in this column. An example photo silver_loyalty_tier.png would be referenced using silver_loyalty_tier.

Note that this update does not modify the actual campaign template. It also cannot be used to add additional strip images to a campaign.

The file body can also include fields which will trigger a notification for Apple devices (Google does not support direct notifications to their Google Pay passes).

Message FieldData TypeDescription
message_templateStringThe push notification message.

Note: Messages are only compatible with Apple Wallet.
message_headerStringThis field will only effect Google Pay passes. This adds a section on the pass that contains a unique message. This field will contain the header value for this new section.

Errors

When uploading a wallet batch file, there are a handful of a common errors you may encounter in the completed file, some of which are normal and don't require any action on your part.

Error: Wallet Item Not Found

This error indicates that our system did not find a live mobile wallet pass that matched the UUID presented. Usually, this means the pass had existed at one point in someone's mobile wallet but has since been removed by the user. Unfortunately, this means your update could not be delivered.

In other scenarios, this could mean that the wallet pass UUID you entered in the file doesn't exist - this could be due to a typo in the csv file, OR because you are referencing the wrong campaign token (meaning you are trying to change data in the wrong campaign, and the UUIDs used exist in a separate campaign).

Updating Custom Fields

It is important to note that Wallet Batch Updates will only change custom fields as they appear on the wallet pass; it will not change the fields in the mobile database itself. To change a mobile database custom field value in the mobile database, you can used the person file.

Example Files

Below, you can download a .zip of example files of a wallet batch update. One example references the campaign token value in each row instead of specifying in the header. This example also displays how to use dynamic strip images via batch file.

To view these files, follow the following steps.

  1. Download example files here.
  2. View the file in your downloads folder. Click to unzip.
  3. Rename each unzipped file by adding .csv to the end. This will change the file's extension, therefore making it viewable in Microsoft Excel.
  4. Open the file in Microsoft Excel or another spreadsheet app to view.

Note that when you upload a wallet batch update in platform, the .csv extension should be deleted.