Common APIs¶
Date and Time Formats¶
Since 15 October 2026, all date and datetime fields in Wallet v3 API requests must be supplied in ISO 8601 format, for example 2026-12-31 for a date or 2026-12-31T17:30:00 for a date and time. Any other format is rejected with error E930. See Date and Time Formats for the accepted formats, timezone handling, the fields covered, and the response fields that are now returned in ISO 8601.
GetPassTemplates¶
The GetPassTemplates API will fetch the list of the Pass Templates present under the account identified by the api-key. This API fetches the data in a paginated way. Users can provide the page number and data needed per page required and API will send the required data.
| Params/Variables | Format | Description |
|---|---|---|
| action | Mandatory, Alphabetic (a-zA-Z) | This is the name of the function you want to execute with the API. |
| x-api-key | Mandatory, Alphanumeric (a-zA-Z0-9), Case-Sensitive. This is set in the request header param. |
This is a random key that is assigned to an account and can be used for authorization. You can find and regenerate this key on the ‘API Settings’ page. |
| page-number | Optional, Numeric | Users can provide the page number using this parameter and the user will receive data from this page number. |
| items-per-page | Optional, Numeric (Default is 100) | Users can provide the count of data required per page and the API will send that amount of data in response. |
Required Parameters:¶
action, x-api-key
Request:¶
{
"action": "getPassTemplates",
"page-number": "PAGE NUMBER",
"items-per-page": "Number of Items to send"
}
Request Example:¶
Response Success Example:¶
{
"status":"success",
"pass-templates": [
{
"pass-template-id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"pass-template-name": "GiftCard-Pass-1",
"pass-template-type": "Gift Card",
"created-timestamp": "2019-10-07T11:57:32",
"last-updated-timestamp": "2019-10-07T11:57:32"
},
{
"pass-template-id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"pass-template-name": "BoardingPass-1",
"pass-template-type": "Boarding Pass",
"created-timestamp": "2019-10-07T11:57:28",
"last-updated-timestamp": "2019-10-07T11:57:28"
}
]
}
Response Failure Example:¶
{
"status": "failure",
"error-code": "E104",
"error-info": "Authentication failed. Invalid api-key."
}
GeneratePassById¶
The generate pass by id API will generate a unique installation link based on the unique ‘pass-id’. If you try to call this API with an invalid ‘pass-id’ or a ‘pass-id’ that is not associated with the pass that you are trying to generate, you will receive an error message. To call this API again successfully, you will need to use a valid ‘pass-id’. The required parameters are action, api-key, pass-id, and pass-template-id.
Request:¶
{
"action":"generatepassbyid",
"pass-id":"CUSTOM PASS ID",
"pass-template-id": "PASS TEMPLATE ID"
}
Request Example:¶
{
"action":"generatepassbyid",
"pass-id":"rockonrock2020",
"pass-template-id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
Request Example:¶
{
"action":"generatepassbyid",
"pass-id":"rockonrock2020",
"pass-template-id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
Response Success Example:¶
{
"status":"Success",
"pass-id":"rockonrock2020",
"pass-install-url":"https://fake-d2c-url.com/wallet/gc/223979as8c23420701f7b9aedbf0c55e?iid=q08e5af653af95a7",
"tracking-id":"xxxxxxxxxx"
}
Response Failure Example:¶
{
"status":"Failure",
"error-code":"E810",
"error-message":"The pass-id value is required.",
"pass-id": "Boarding 123"
}
DeletePassData¶
The delete pass data API is used to remove data for a Pass that has already been installed on a device. Using this API will only delete the pass data associated with the ‘pass-id’ from our system. This does not remove or uninstall the Pass from the device. If you receive a failure message, the Pass data has not been deleted. The required params are action, api-key, pass-id, and pass-template-id .
Request:¶
{
"action":"deletepassdata",
"pass-id":"CUSTOM PASS ID",
"pass-template-id" :"PASS TEMPLATE ID"
}
Request Example:¶
{
"action":"deletepassdata",
"pass-id":"rockonrock2020",
"pass-template-id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
Response Success Example:¶
Response Failure Example:¶
{
"status" : "Failure",
"error-code" : "E821",
"error-message" : "Internal Error. The pass was not deleted.",
"pass-id":"rockonrock2020"
}
GetPassIds¶
The GetPassIds API will fetch a list of passes, generated for a given Pass Template under the user account identified by the api-key. This API fetches the data in a paginated way. Users can provide the page number and data needed per page required and API will send the required data.
| Params/Variables | Format | Description |
|---|---|---|
| action | Mandatory, Alphabetic (a-zA-Z) | This is the name of the function you want to execute with the API. |
| x-api-key | Mandatory, Alphanumeric (a-zA-Z0-9), Case-Sensitive. This is set in the request header param. |
This is a random key that is assigned to an account and can be used for authorization. You can find and regenerate this key on the ‘API Settings’ page. |
| pass-template-id | Mandatory, Alphanumeric (a-zA-Z0-9), Case-Sensitive | This is the unique Pass Template ID used to reference a particular Pass Template. |
| page-number | Optional, Numeric | Users can provide the page number using this parameter and the user will receive data from this page number. |
| items-per-page | Optional, Numeric (Default is 100) | Users can provide the count of data required per page and the API will send that amount of data in response. |
Request:¶
{
"action": "getPassIds",
"pass-template-id" : "PASS TEMPLATE ID",
"page-number": "PAGE NUMBER",
"items-per-page": "Number of Items to send"
}
Request Example:¶
{
"action":"getpassids",
"pass-template-id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"page-number":"1",
"items-per-page":"2"
}
Response Success Example:¶
{
"status":"success",
"pass-template-id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"pass-ids":[
{
"pass-id":"GC-feb-17.3we",
"created-timestamp":"2020-03-09T18:22:36",
"last-updated-timestamp":"2020-03-09T18:22:36"
},
{
"pass-id":"GC-feb-17.Gpay",
"created-timestamp":"2020-02-26T14:36:12",
"last-updated-timestamp":"2020-03-11T14:27:20"
}
]
}
Response Failure Example:¶
{
"status":"Failure",
"error-code":"E827",
"error-message":"items-per-page is invalid. Only numeric values are allowed.",
"pass-template-id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
GetPassTemplateStats¶
The GetPassTemplateStats API returns the pass record and pass install stats for one Pass Template over a date range. These are the same figures shown on the Pass Records and Pass Installs pages of your WalletThat account.
The response contains:
totals: the counts summed across the whole requested range.daily-stats: one entry per calendar day in the range, oldest first. Each entry has the same fields astotals, plus thedate. Days with no activity are returned with every count set to0, so the array always covers every day in the range.
Dates are calendar days in your account timezone. All dates use ISO 8601 format (YYYY-MM-DD).
| Params/Variables | Format | Description |
|---|---|---|
| action | Mandatory, Alphabetic (a-zA-Z) | This is the name of the function you want to execute with the API. Use getPassTemplateStats. |
| x-api-key | Mandatory, Alphanumeric (a-zA-Z0-9), Case-Sensitive. This is set in the request header param. |
This is a random key that is assigned to an account and can be used for authorization. You can find and regenerate this key on the ‘API Settings’ page. |
| pass-template-id | Mandatory, Alphanumeric (a-zA-Z0-9), Case-Sensitive | This is the unique Pass Template ID used to reference a particular Pass Template. The Pass Template must belong to the account identified by the api-key. |
| period | Mandatory, one of: today, last_7_days, last_30_days, last_60_days, last_year, custom |
The date range to report on. Every period except custom ends today, in the account timezone, and includes today. last_7_days, last_30_days and last_60_days cover 7, 30 and 60 days, and last_year covers 365 days. Use custom to set your own range with start-date and end-date. |
| start-date | Mandatory when period is custom, ISO 8601 date (YYYY-MM-DD) |
The first day of the custom range, included in the results. Ignored for other periods. |
| end-date | Mandatory when period is custom, ISO 8601 date (YYYY-MM-DD) |
The last day of the custom range, included in the results. Ignored for other periods. |
Required Parameters:¶
action, x-api-key, pass-template-id, period
start-date and end-date are also required when period is custom.
Custom Date Range Rules¶
When period is custom:
- start-date and end-date must both be valid ISO 8601 dates (
YYYY-MM-DD). Dates with a time component are not accepted. - Both dates must be between
1970-01-01and the current date in the account timezone. Future dates are rejected with error E1611. - end-date must be the same as or later than start-date. Set both to the same date for a single day.
- The range may cover at most 366 days, counting both start-date and end-date. A longer range is rejected with error E1609. It is not shortened automatically.
Response Fields¶
Each of the following fields is returned in totals and in every daily-stats entry.
| Field | Description |
|---|---|
| records-added | Number of pass records added. |
| records-archived | Number of pass records archived. |
| records-updated | Number of pass record updates. This counts update events, not distinct records: a record updated three times counts as three. |
| records-redeemed | Number of pass records redeemed. |
| records-voided | Number of pass records voided. |
| records-expired | Number of pass records expired. |
| passes-installed-apple | Number of passes installed in Apple Wallet. |
| passes-uninstalled-apple | Number of passes uninstalled from Apple Wallet. |
| passes-installed-google | Number of passes installed in Google Wallet. |
| passes-uninstalled-google | Number of passes uninstalled from Google Wallet. |
The response also echoes pass-template-id and period, returns the resolved start-date and end-date of the range, and includes a tracking-id.
How the install figures are counted
- The four
passes-*fields count only live pass records. When a pass record is archived, its installs and uninstalls are removed from the figures, including for days already reported. The same rule applies on the Pass Installs page. Therecords-*fields are not affected by archiving. - If a pass is installed or uninstalled more than once, only the most recent install and the most recent uninstall are counted. Because of this, the Apple and Google figures may not add up exactly to the combined install and uninstall totals shown elsewhere in your account.
Request:¶
{
"action": "getPassTemplateStats",
"pass-template-id": "PASS TEMPLATE ID",
"period": "PERIOD",
"start-date": "YYYY-MM-DD",
"end-date": "YYYY-MM-DD"
}
Request Example:¶
{
"action": "getPassTemplateStats",
"pass-template-id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"period": "last_30_days"
}
Request Example (custom range):¶
{
"action": "getPassTemplateStats",
"pass-template-id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"period": "custom",
"start-date": "2026-07-01",
"end-date": "2026-07-31"
}
Response Success Example:¶
The daily-stats array is shortened here. A last_30_days response has 30 entries, one for each day from start-date to end-date.
{
"status": "success",
"pass-template-id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"period": "last_30_days",
"start-date": "2026-07-14",
"end-date": "2026-08-12",
"totals": {
"records-added": 340,
"records-archived": 22,
"records-updated": 118,
"records-redeemed": 90,
"records-voided": 4,
"records-expired": 11,
"passes-installed-apple": 205,
"passes-uninstalled-apple": 48,
"passes-installed-google": 130,
"passes-uninstalled-google": 31
},
"daily-stats": [
{
"date": "2026-07-14",
"records-added": 12,
"records-archived": 1,
"records-updated": 4,
"records-redeemed": 3,
"records-voided": 0,
"records-expired": 0,
"passes-installed-apple": 8,
"passes-uninstalled-apple": 2,
"passes-installed-google": 5,
"passes-uninstalled-google": 1
},
{
"date": "2026-07-15",
"records-added": 0,
"records-archived": 0,
"records-updated": 0,
"records-redeemed": 0,
"records-voided": 0,
"records-expired": 0,
"passes-installed-apple": 0,
"passes-uninstalled-apple": 0,
"passes-installed-google": 0,
"passes-uninstalled-google": 0
}
],
"tracking-id": "xxxxxxxxxx"
}
Response Failure Example:¶
{
"status": "failure",
"error-code": "E1609",
"error-message": "The requested date range is too large. A custom range may cover at most 366 days.",
"pass-template-id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
Error Codes¶
In addition to the General Error Codes, this API can return the following errors.
| Code | Description |
|---|---|
| E801 | The pass-template-id value is required. |
| E802 | The pass-template-id value is invalid. |
| E1605 | The period value is required. Allowed values are: today, last_7_days, last_30_days, last_60_days, last_year, custom. |
| E1606 | The period value is invalid. Allowed values are: today, last_7_days, last_30_days, last_60_days, last_year, custom. |
| E1607 | The start-date (or end-date) value is required when period is set to custom. |
| E1608 | The start-date (or end-date) value is invalid. Dates must be in ISO 8601 date format (YYYY-MM-DD). |
| E1609 | The requested date range is too large. A custom range may cover at most 366 days. |
| E1610 | The end-date must be the same as or later than the start-date. |
| E1611 | The start-date (or end-date) value is out of range. Dates must be between 1970-01-01 and the current date (YYYY-MM-DD). |