Update Dynamic Pass Template API

Overview

The Update Dynamic Pass Template API allows you to modify existing dynamic pass templates. When a template is updated, all passes that were created from this template will automatically be updated with the new template design and structure. This ensures consistency across all passes generated from the template while preserving the individual dynamic data for each pass.

⚠️ Automatic Pass Updates

Every pass already created from this template is re-rendered in the background to reflect the new design — this may take a few minutes for large numbers of passes. The per-customer dynamic data is preserved, and the customers in the template's linked user group are left untouched.

🔁 Loyalty templates

This endpoint also updates loyalty templates, but the update replaces the whole template — send the complete object (keep cardSubType and loyaltyProgressData) and note that the stamp / counter images are not regenerated here. See Create Loyalty Template → Updating & deleting for the full caveats.

Base URL

https://app.addtowallet.co

PUT/api/dynamicPass/template/:dynamicpassId

Path Parameters

dynamicpassId (string, required): The unique identifier of the dynamic pass template to update

Authentication

All API requests must include your API key in the request headers:

"apikey": "your-api-key-here"

Request Parameters

The API accepts the following parameters in the request body JSON. All parameters are optional - only provide the fields you want to update. At least one field must be provided.

Request Parameters

Name	Type	Required	Description
name	`string`	No	Update the template name (max 100 characters)
description	`string`	No	Update the template description
templateData	`object`	No	Update the pass template configuration. This can be a partial update - only the fields provided will be modified
dynamicFields	`array<string>`	No	Update the list of dynamic fields. This will replace the existing list completely

Access code protection

templateData may include accessCode. Static values max 10 characters, or {dynamicFieldName} for per-recipient codes (must match a name in dynamicFields). Resolved values must be 10 characters or fewer. Recipients verify on the AddToWallet hosted card or embed page — you do not need to implement preview verification.

Important Notes

• When updating templateData, existing passes will be updated with the new template structure
• Dynamic field values for individual passes are preserved
• If you remove a dynamic field from the dynamicFields array, those placeholders will remain static in existing passes
• Adding new dynamic fields will create placeholders that can be populated in future pass updates
• All customers in the associated user group maintain their data during template updates

⚠️ Text Modules Validation

The textModulesData field inside templateData follows the same validation rules as on creation (valid IDs, max items, required header/body). See Create Template → Text Modules Validation for the full rules.

Apple Thumbnail & Background (optional)

Sending thumbnailImage and/or backgroundImage enables Apple event-ticket layout automatically — do not send a layout switch field.
Google: still use googleHeroImage / heroImage; thumbnail does not replace the Google hero.
Apple: when thumbnail/background are set, appleHeroImage is not used for the Apple strip.
backgroundImage is optional; Apple falls back to hexBackgroundColor.
With thumbnailImage, textModulesData renders in a three-column auxiliary row; without thumbnail, fields use the secondary row.
On update, send null or an empty string to remove an image; when both are cleared, the pass reverts to strip layout.
When backgroundImage is set, set explicit appleFontColor and appleLabelColor for readable text.
Dynamic placeholders are supported — e.g. "thumbnailImage": "{photoUrl}" inside templateData (must match a name in dynamicFields).

Apple Thumbnail & Background

Name	Type	Required	Description
templateData.thumbnailImage	`string`	No	Apple square thumbnail image URL (~90×90 in Wallet). Sending this and/or backgroundImage enables Apple event-ticket layout automatically — no layout field needed.
templateData.backgroundImage	`string`	No	Optional Apple full-card background image (180×220 aspect). Also enables event-ticket layout when set alone. Apple falls back to hexBackgroundColor when omitted.

Partial Updates

You can perform partial updates by providing only the fields you want to change. For example, to update only the template name and background color:

{
  "name": "New Template Name",
  "templateData": {
    "hexBackgroundColor": "#ff5722"
  }
}

Request Example

curl -X PUT 'https://api.addtowallet.co/api/dynamicPass/template/686d0d92c2f0bc5cdf25c834' \
  -H 'apikey: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Employee Business Card Template",
    "description": "Updated template with new branding and additional fields",
    "templateData": {
      "logoUrl": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
      "cardTitle": "{companyName}",
      "header": "{employeeName}",
      "subheader": "{department}",
      "textModulesData": [
        { "id": "r1start", "header": "Position", "body": "{position}" },
        { "id": "r1middle", "header": "Department", "body": "{department}" },
        { "id": "r1end", "header": "Phone", "body": "{phone}" }
      ],
      "hexBackgroundColor": "#2c3e50"
    }
  }'

Response

Upon successful update, the API returns a JSON object containing:

message (string): A success message confirming the template update
passesUpdated (number): The number of individual passes that were queued for update as a result of this template change
batchId (string|null): The batch ID for tracking the update process (null if no passes need updating)

Response Example

{
  "message": "Template updated and pass updates queued successfully",
  "passesUpdated": 25,
  "batchId": "66c7d92f3e8b1a2c4d5e6f78"
}

💡 Batch Processing

When the response includes a batchId, poll the Batch Status endpoint (GET /api/v2/batch/status/:batchId) to monitor the progress of the pass updates.

Error Code	Description
400	BAD_REQUEST - Missing required parameters, invalid data format, or empty request body
401	UNAUTHORIZED - Valid API key required
404	NOT_FOUND - Template not found or insufficient permissions
500	SERVER_ERROR - Database error or unexpected server issue

Update Dynamic Pass Template API

Overview

⚠️ Automatic Pass Updates

🔁 Loyalty templates

Base URL

https://app.addtowallet.co

PUT/api/dynamicPass/template/:dynamicpassId

Path Parameters

dynamicpassId (string, required): The unique identifier of the dynamic pass template to update

Authentication

All API requests must include your API key in the request headers:

"apikey": "your-api-key-here"

Request Parameters

The API accepts the following parameters in the request body JSON. All parameters are optional - only provide the fields you want to update. At least one field must be provided.

Request Parameters

Name	Type	Required	Description
name	`string`	No	Update the template name (max 100 characters)
description	`string`	No	Update the template description
templateData	`object`	No	Update the pass template configuration. This can be a partial update - only the fields provided will be modified
dynamicFields	`array<string>`	No	Update the list of dynamic fields. This will replace the existing list completely

Access code protection

Important Notes

• When updating templateData, existing passes will be updated with the new template structure
• Dynamic field values for individual passes are preserved
• If you remove a dynamic field from the dynamicFields array, those placeholders will remain static in existing passes
• Adding new dynamic fields will create placeholders that can be populated in future pass updates
• All customers in the associated user group maintain their data during template updates

⚠️ Text Modules Validation

Apple Thumbnail & Background (optional)

Sending thumbnailImage and/or backgroundImage enables Apple event-ticket layout automatically — do not send a layout switch field.
Google: still use googleHeroImage / heroImage; thumbnail does not replace the Google hero.
Apple: when thumbnail/background are set, appleHeroImage is not used for the Apple strip.
backgroundImage is optional; Apple falls back to hexBackgroundColor.
With thumbnailImage, textModulesData renders in a three-column auxiliary row; without thumbnail, fields use the secondary row.
On update, send null or an empty string to remove an image; when both are cleared, the pass reverts to strip layout.
When backgroundImage is set, set explicit appleFontColor and appleLabelColor for readable text.
Dynamic placeholders are supported — e.g. "thumbnailImage": "{photoUrl}" inside templateData (must match a name in dynamicFields).

Apple Thumbnail & Background

Name	Type	Required	Description
templateData.thumbnailImage	`string`	No	Apple square thumbnail image URL (~90×90 in Wallet). Sending this and/or backgroundImage enables Apple event-ticket layout automatically — no layout field needed.
templateData.backgroundImage	`string`	No	Optional Apple full-card background image (180×220 aspect). Also enables event-ticket layout when set alone. Apple falls back to hexBackgroundColor when omitted.

Partial Updates

You can perform partial updates by providing only the fields you want to change. For example, to update only the template name and background color:

{
  "name": "New Template Name",
  "templateData": {
    "hexBackgroundColor": "#ff5722"
  }
}

Request Example

curl -X PUT 'https://api.addtowallet.co/api/dynamicPass/template/686d0d92c2f0bc5cdf25c834' \
  -H 'apikey: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Employee Business Card Template",
    "description": "Updated template with new branding and additional fields",
    "templateData": {
      "logoUrl": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
      "cardTitle": "{companyName}",
      "header": "{employeeName}",
      "subheader": "{department}",
      "textModulesData": [
        { "id": "r1start", "header": "Position", "body": "{position}" },
        { "id": "r1middle", "header": "Department", "body": "{department}" },
        { "id": "r1end", "header": "Phone", "body": "{phone}" }
      ],
      "hexBackgroundColor": "#2c3e50"
    }
  }'

Response

Upon successful update, the API returns a JSON object containing:

message (string): A success message confirming the template update
passesUpdated (number): The number of individual passes that were queued for update as a result of this template change
batchId (string|null): The batch ID for tracking the update process (null if no passes need updating)

Response Example

{
  "message": "Template updated and pass updates queued successfully",
  "passesUpdated": 25,
  "batchId": "66c7d92f3e8b1a2c4d5e6f78"
}

💡 Batch Processing

When the response includes a batchId, poll the Batch Status endpoint (GET /api/v2/batch/status/:batchId) to monitor the progress of the pass updates.

Error Code	Description
400	BAD_REQUEST - Missing required parameters, invalid data format, or empty request body
401	UNAUTHORIZED - Valid API key required
404	NOT_FOUND - Template not found or insufficient permissions
500	SERVER_ERROR - Database error or unexpected server issue