Update Pass API

Overview

The Update Pass API allows you to modify existing digital passes. This endpoint accepts updated pass details and returns a confirmation of the changes applied to the pass.

Base URL

https://app.addtowallet.co

PUT/api/card/edit/{cardId}

Authentication

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

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

Request Parameters

Include only the fields you want to update. Below are common update fields.

New Image Options

Platform-Specific Images

Use googleHeroImage and appleHeroImage to optimize images for each platform. If only heroImage is provided, it will be used as a fallback for both platforms. Platform-specific images take precedence over the general heroImage. Watermarking is handled automatically based on your plan; no raw image URLs are required. For Apple event-ticket layout with thumbnail/background instead of the Apple strip, see Apple Thumbnail & Background below.

Request Parameters

Name	Type	Required	Description
rectangleLogo	`string`	No	URL for a rectangle/wide logo that replaces both the round logo and card title
googleHeroImage	`string`	No	URL for Google Wallet specific hero image
appleHeroImage	`string`	No	URL for Apple Wallet specific hero image

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.

Apple Thumbnail & Background

Name	Type	Required	Description
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.
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.

Access Protection (Optional)

Recipients enter the code on the AddToWallet hosted card or embed page before previewing or downloading the pass. You do not need to implement preview verification in your integration.

Request Parameters

Name	Type	Required	Description
accessCode	`string \| null`	No	Require an access code before preview/download. Static values max 10 characters. Send `null` or empty string to clear.

Notification Settings (Optional)

Update Scheduled Notifications

You can update or add scheduled notification settings to existing passes. See the Notifications API for details.

Request Parameters

Name	Type	Required	Description
notificationValues	`array<string> \| string`	No	One or more scheduled notifications to enable. upcomingNotification triggers before startDate; expiryNotification before endDate; locationNotification uses locations. `beaconNotification` is Apple Wallet iBeacon only (use `appleBeacons` or `beacons`). Google notification priority ignores beacons. Allowed: `upcomingNotification`, `expiryNotification`, `locationNotification`, `beaconNotification`
appleBeacons	`array<Beacon>`	No	Apple only: up to 10 iBeacon rows when using beaconNotification (alias `beacons`). PKPass includes `proximityUUID`, `major`, `minor`, optional `relevantText`.
proximityUUID	`string`	Yes	iBeacon UUID
major	`number`	Yes	0–65535
minor	`number`	Yes	0–65535
relevantText	`string`	No	Optional lock-screen message
startDate	`string`	Conditional	ISO date required when notificationValues includes upcomingNotification
endDate	`string`	Conditional	ISO date required when notificationValues includes expiryNotification
locations	`array<Location> \| Location`	No	Merchant locations for proximity notifications (up to 10). Optional message maps to Apple relevantText.
latitude	`number`	Yes	Latitude (-90 to 90)
longitude	`number`	Yes	Longitude (-180 to 180)
message	`string`	No	Apple only: custom text when near this location
altitude	`number`	No	Optional altitude in meters

{
  "logoUrl": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
  "cardTitle": "ACME Corp",
  "header": "Joe",
  "subheader": "Senior Developer",
  "textModulesData": [
    {
      "id": "r1start",
      "header": "Phone",
      "body": "+1 8888888888"
    },
    {
      "id": "r1end",
      "header": "Email",
      "body": "[email protected]"
    }
  ],
  "linksModuleData": [
    {
      "id": "r1",
      "description": "Call Us",
      "uri": "tel:+1 8287489293"
    },
    {
      "id": "r2",
      "description": "Email Us",
      "uri": "mailto:[email protected]"
    },
    {
      "id": "r3",
      "description": "Visit our website",
      "uri": "https://app.addtowallet.co"
    },
    {
      "id": "r4",
      "description": "Visit our office",
      "uri": "geo:https://maps.google.com/?q=123+Main+Street,+Anytown,+CA"
    }
  ],
  "barcodeType": "QR_CODE",
  "barcodeValue": "",
  "barcodeAltText": "",
  "hexBackgroundColor": "#043482",
  "appleFontColor": "#FFFFFF",
  "changedAppleFontColor": false,
  "heroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
  "rectangleLogo": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
  "googleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
  "appleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png"
}

Response

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

msg (string): A success message confirming the update
updateStatus (object): MongoDB update operation status
- acknowledged (boolean): Whether the update was acknowledged
- modifiedCount (number): Number of documents modified
- matchedCount (number): Number of documents matched

Error Codes

The API may return the following error status codes:

Status Code	Error	Description
400	Bad Request	Missing required fields, invalid parameter values, or invalid image dimensions (hero images must be at least 200x100 pixels)
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions or exceeding usage limits
404	Not Found	Pass with the specified ID does not exist
429	Too Many Requests	API rate limit exceeded. Try again later
500	Internal Server Error	Unexpected server error. Please contact support

Update Pass API

Overview

The Update Pass API allows you to modify existing digital passes. This endpoint accepts updated pass details and returns a confirmation of the changes applied to the pass.

Base URL

https://app.addtowallet.co

PUT/api/card/edit/{cardId}

Authentication

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

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

Request Parameters

Include only the fields you want to update. Below are common update fields.

New Image Options

Platform-Specific Images

Request Parameters

Name	Type	Required	Description
rectangleLogo	`string`	No	URL for a rectangle/wide logo that replaces both the round logo and card title
googleHeroImage	`string`	No	URL for Google Wallet specific hero image
appleHeroImage	`string`	No	URL for Apple Wallet specific hero image

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.

Apple Thumbnail & Background

Name	Type	Required	Description
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.
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.

Access Protection (Optional)

Recipients enter the code on the AddToWallet hosted card or embed page before previewing or downloading the pass. You do not need to implement preview verification in your integration.

Request Parameters

Name	Type	Required	Description
accessCode	`string \| null`	No	Require an access code before preview/download. Static values max 10 characters. Send `null` or empty string to clear.

Notification Settings (Optional)

Update Scheduled Notifications

You can update or add scheduled notification settings to existing passes. See the Notifications API for details.

Request Parameters

Name	Type	Required	Description
notificationValues	`array<string> \| string`	No	One or more scheduled notifications to enable. upcomingNotification triggers before startDate; expiryNotification before endDate; locationNotification uses locations. `beaconNotification` is Apple Wallet iBeacon only (use `appleBeacons` or `beacons`). Google notification priority ignores beacons. Allowed: `upcomingNotification`, `expiryNotification`, `locationNotification`, `beaconNotification`
appleBeacons	`array<Beacon>`	No	Apple only: up to 10 iBeacon rows when using beaconNotification (alias `beacons`). PKPass includes `proximityUUID`, `major`, `minor`, optional `relevantText`.
proximityUUID	`string`	Yes	iBeacon UUID
major	`number`	Yes	0–65535
minor	`number`	Yes	0–65535
relevantText	`string`	No	Optional lock-screen message
startDate	`string`	Conditional	ISO date required when notificationValues includes upcomingNotification
endDate	`string`	Conditional	ISO date required when notificationValues includes expiryNotification
locations	`array<Location> \| Location`	No	Merchant locations for proximity notifications (up to 10). Optional message maps to Apple relevantText.
latitude	`number`	Yes	Latitude (-90 to 90)
longitude	`number`	Yes	Longitude (-180 to 180)
message	`string`	No	Apple only: custom text when near this location
altitude	`number`	No	Optional altitude in meters

{
  "logoUrl": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
  "cardTitle": "ACME Corp",
  "header": "Joe",
  "subheader": "Senior Developer",
  "textModulesData": [
    {
      "id": "r1start",
      "header": "Phone",
      "body": "+1 8888888888"
    },
    {
      "id": "r1end",
      "header": "Email",
      "body": "[email protected]"
    }
  ],
  "linksModuleData": [
    {
      "id": "r1",
      "description": "Call Us",
      "uri": "tel:+1 8287489293"
    },
    {
      "id": "r2",
      "description": "Email Us",
      "uri": "mailto:[email protected]"
    },
    {
      "id": "r3",
      "description": "Visit our website",
      "uri": "https://app.addtowallet.co"
    },
    {
      "id": "r4",
      "description": "Visit our office",
      "uri": "geo:https://maps.google.com/?q=123+Main+Street,+Anytown,+CA"
    }
  ],
  "barcodeType": "QR_CODE",
  "barcodeValue": "",
  "barcodeAltText": "",
  "hexBackgroundColor": "#043482",
  "appleFontColor": "#FFFFFF",
  "changedAppleFontColor": false,
  "heroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
  "rectangleLogo": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
  "googleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
  "appleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png"
}

Response

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

msg (string): A success message confirming the update
updateStatus (object): MongoDB update operation status
- acknowledged (boolean): Whether the update was acknowledged
- modifiedCount (number): Number of documents modified
- matchedCount (number): Number of documents matched

Error Codes

The API may return the following error status codes:

Status Code	Error	Description
400	Bad Request	Missing required fields, invalid parameter values, or invalid image dimensions (hero images must be at least 200x100 pixels)
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions or exceeding usage limits
404	Not Found	Pass with the specified ID does not exist
429	Too Many Requests	API rate limit exceeded. Try again later
500	Internal Server Error	Unexpected server error. Please contact support