Updating Wallet Passes via Flat Files

The Wallet Crew supports updating passes using flat file uploads. This method is ideal for bulk updates or integration with legacy systems that generate CSV exports.

Process Overview

1. Upload your CSV file to the provided SFTP server.
2. The Wallet Crew automatically detects new files and processes them immediately.
3. Once processed, file will be moved to .processed folder or .error
4. Each row is interpreted as an update instruction for a single pass.
5. Passes are queued for update and processed asynchronously.

File Format

Uploaded files must be valid RFC 4180 compliant CSV files.

• Separators: Either , or ;
• Header row: Mandatory. Must contain column names.
• Encoding: UTF-8 recommended
• Parser: The Wallet Crew uses CsvHelper with default options

Each data row targets a single pass and can include multiple updates to its fields, additionalData, or metadata.

File Name

There are no strict file name requirements. However, for better organization and traceability, we recommend the following naming convention:

<source>-passes-<YYYYMMDD>-<HHMMSS>.csv

Examples:

crm-passes-20250801-083000.csv 
loyalty-passes-20250731-235959.csv

Notes:

• The file extension must be .csv
• Avoid using special characters (spaces, #, %, &, etc.) in file names
• If you are using a script or integration to generate files, adopting a timestamp-based naming pattern helps avoid duplication and makes debugging easier.
• If the file is large, The Wallet Crew will briefly monitor its size for a few milliseconds to ensure it has been fully written before processing.

Column Reference

Identifiers

To select the target pass, use one of the following columns:

• id: Internal The Wallet Crew pass identifier
• id.<externalId>: External identifier name (as configured in your Wallet Crew instance)
  Example: id.y2.customerId

At least one identifier column must be present in each row.

Additional Data

To update additional data on the pass, use the following syntax:

• additionalData.<key>: Updates the key in the pass’s additionalData dictionary
  Example: additionalData.notification_content

Multiple additionalData keys can be updated in one row.

Pass Template

To switch the pass to a different template, include:

• passType: The new template name (as defined in The Wallet Crew)

If omitted or empty, the pass will retain its current template.

Metadata Refresh

To trigger a recomputation of internal metadata (e.g., barcodes, expiration, display fields):

• updateMetadata: Set to true to trigger metadata update

SFTP Access

You can upload your CSV files to our dedicated SFTP endpoints:

Contact The Wallet Crew Support to request your SFTP credentials.

Examples

Example 1: Update Notification and Offer URL

id;additionalData.notification_content;additionalData.offer_url
Gk440DNzvfZcDmlA;Merry Christmas Alice!;https://acme.com/xmas1
HKlhrhrEXx2ZASYs;Merry Christmas Bob!;https://acme.com/xmas1

Example 2: Update by External ID with Loyalty Info

id.y2.customerId;additionalData.notification_content
00100123;Enjoy 30% off on your next purchase
04503295;Thanks for your purchase! Only 10 points left to redeem a €10 voucher
02319202;Thanks for your purchase! Only 120 points left to redeem a €10 voucher

Example 3: Switch Pass Template and Force Metadata Refresh

id;passType;updateMetadata
gH67xKlPzLZ99xa2;vip_template;true
dAk21jvUZYx39q77;standard_template;true

Extensibility and Custom Mapping

The Wallet Crew supports custom file transformations using import scripts.

This allows you to:

• Adapt your existing export format (e.g., from a CRM or POS)
• Map legacy column names to The Wallet Crew-compatible keys
• Inject dynamic values (e.g., current date, calculated points)
• Enrich data with lookups from external sources

To customize the import process, you can create a import.custom.js file in the scripts folder on the advanced configuration.

If you have the following CSV file :

id.y2.customerId,neo_notification_content,neo_offer_title,neo_offer_body
abc12345,"Hey Arthur !","Your 20% offer","20% Off for your next purchase"

You can use the following script :

function transform(row){
  const identifiers = {
      "id.y2.customerId" : row["id.y2.customerId"]
  };

  const passType = row.passType || null; 

  const properties = [
    "notification_content",
    "offer_title", 
    "offer_body"
   ];

  let additionalData = {};
  for(const property of properties){
    if(row["neo_" + property] !== undefined){
      additionalData[property] = row["neo_" + property].toString(); 
    }
  }

  return {
    Identifiers : identifiers, 
    PassType: passType,
    AdditionalData : additionalData
  }
}

export default function(context) {
  context.register('runtime.import.updatePasses.rowTransformer', {
    Transform: transform
  });
}

Contact our team if you need help implementing custom mapping logic for your imports.

Tips and Best Practices

• Ensure identifiers are accurate to avoid skipped rows.
• Always test your file format in QA before uploading to production.
• Use consistent encoding (UTF-8) to avoid parsing issues with special characters.