Update pass using flat files

Bulk update wallet passes by uploading RFC 4180 CSV files via SFTP.

The Wallet Crew can update existing Apple Wallet and Google Wallet passes from a CSV file. This is useful for bulk updates and for legacy systems that can only export flat files.

SFTP imports are an optional feature. Ask The Wallet Crew to enable SFTP on your tenant before implementing this flow.

Treat SFTP imports as a last resort. Avoid this flow unless you have no other option (for example, a legacy system that can only export flat files).

For most projects, the API is the recommended approach. It is easier to automate, easier to monitor, and updates in real time.

If you prefer a real-time integration, use the API update flow instead. See Leveraging Updated Pass Data with The Wallet Crew API.

Real-world examples

• A gift card program recalculates balance every hour. A flat file export updates additionalData.balance for all active cards.

• A marketing automation team exports a CSV to prepare a push campaign. Each row updates additionalData.notification_content before sending notifications.

• A ticketing system exports last-minute changes (gate, seat, or schedule). A bulk CSV update keeps tickets accurate right before doors open.

• A gym chain exports membership status every night (active, frozen, expired). The next day, members see the correct status at check-in.

• A support team fixes a wrong identifier at scale by uploading a one-time correction file.

Flat file imports let you update many passes in one operation.

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, the file is moved to .processed/ 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{target="_blank"} compliant CSV files.

• Separators: Either , or ;

• Header row: Mandatory. Must contain column names.

• Encoding: UTF-8 recommended

• Parser: The Wallet Crew uses CsvHelper{target="_blank"} 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 briefly monitors its size to ensure it is fully written before processing.

Column reference

Pass identifier columns

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 tenant) Example: id.y2.customerId

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

Additional data columns

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

External identifiers

To update an external identifier, use the following syntax:

• identifiers.<idName>: Updates the identifier named idName Example: identifiers.y2.customerId

SFTP access

Upload your CSV files to the SFTP endpoint for your environment:

• QA: triglav-qa.walletcrew.net (port 22)

• Production: triglav.walletcrew.net (port 22)

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

Example 4: Update external id y2.customerId and force metadata refresh

id.y2.customerId;identifiers.y2.customerId;passType;updateMetadata
04503295;1010013295;;true
04503296;1010013296;;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 an import.custom.js file in the scripts/ folder in 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:

/**
 * Transforms a CSV row into an UpdatePassInformation-like object.
 *
 * @param {Object<string, string>} row - The CSV row, as a dictionary of column names to values.
 * @returns {Object} Transformed row information.
 * @returns {Object<string, string>} return.Identifiers - Identifiers for this row (e.g., customer ID).
 * @returns {string|null} return.PassType - The type of pass, or null if not present.
 * @returns {Object<string, string>} return.AdditionalData - Optional additional data from prefixed columns.
 */
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
  }
}

/**
 * Optional method to return a custom throughput for a given import file.
 *
 * @param {string} fileName - The import file name.
 * @returns {number|null} Throughput override, or null to use default.
 */
function getThroughput(fileName) {
  // Example: return null to use default
  return null;
}

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

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.

FAQ

Do you create new passes, or only update existing ones?

This flow updates existing passes. Each row must target a pass using id or an external identifier column like id.y2.customerId.

What happens if a row has both id and id.<externalId>?

Use one identifier per row if you can. If you include several, make sure they all point to the same pass. This avoids ambiguity and makes troubleshooting easier.

Can I update multiple additionalData keys in one row?

Yes. Add one column per key, using additionalData.<key>. The row will update all provided keys in one pass update.