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.
| Header | Required | Description |
|---|---|---|
| Fields | No | This 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. |
| Delimiter | No | The character used to delimit the columns. Defaults to a comma ",". |
| Campaign-Token | No 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 Name | Data Type | Description |
|---|---|---|
| uuid | String | The pass unique identifier. |
| campaign_token | String | This 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_date | String | If 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) | String | Dynamic 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 remain In 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_CODE | String | If 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 Field | Data Type | Description |
|---|---|---|
| message_template | String | The push notification message. Note: Messages are only compatible with Apple Wallet. |
| message_header | String | This 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. |
| message_image_url | String |
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.
Sample Files
You can download and use the following sample files. To view them in Excel, add .csv to the end of the file name. However, remember when they are uploaded via SFTP, they must be uploaded without the .csv file type extension).
An additional example, referencing 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.
Updated 12 months ago