Pass lifecycle
Void, remove, delete
A pass is Active, Voided, Removed or Deleted. Three calls end it and several change it without ending it. Their names overlap; this page says which does what. Run each on a pass from your sandbox: nothing here reaches a phone.
Ending a pass
| Call | Moves it to | Undo | What it does |
|---|---|---|---|
void | Voided | unvoid | Marks the pass void and republishes it. Scans are refused. |
remove | Removed | restore | Publishes a last version that is voided and expired, so Wallet moves it to Expired passes. The record stays. message shows on the lock screen. |
DELETE | Deleted | none | Deletes the record and frees its externalId. Wallet keeps the pass on the device and sends it no more updates. |
Pick void to pause a pass, remove to take it out of a wallet and keep the record, DELETE only when the record itself must go. Void a pass before you delete it if its holder should see why.
Changing a pass that stays Active
| Call | What changes | Old value |
|---|---|---|
update | Fields, as a new version. | Kept in the version list. |
refresh | Rebuilds the pass from its connection and pushes it again. | Replaced. |
renew | The pass's term. | Replaced. |
new-code | The scan code. Same serial and holder. | Stops scanning. Three a pass an hour. |
rotate-link | The download and public links. The pass itself is unchanged. | Stops working. |
bulk-reissue | Rebuilds every pass of a template. | Replaced. |
Email has two names for two things: resend-email sends a pass's email, send-email sends a bundle's.
Void and undo
curl -X POST "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/void" \ -H "Authorization: Bearer $PASSBOOK_KEY"import { PassBook } from '@passbook/sdk';const pb = new PassBook({ apiKey: process.env.PASSBOOK_KEY ?? '' });const pass = await pb.passes.void('0193a1b2-7c00-7000-8000-0000000000c1');console.log(pass.status);curl -X POST "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/unvoid" \ -H "Authorization: Bearer $PASSBOOK_KEY"import { PassBook } from '@passbook/sdk';const pb = new PassBook({ apiKey: process.env.PASSBOOK_KEY ?? '' });const pass = await pb.passes.unvoid('0193a1b2-7c00-7000-8000-0000000000c1');console.log(pass.status);The pass answers with status: "voided", then "active". Paste the pass id into the path.
Remove and restore
curl -X POST "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/remove" \ -H "Authorization: Bearer $PASSBOOK_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "Refunded"}'import { PassBook } from '@passbook/sdk';const pb = new PassBook({ apiKey: process.env.PASSBOOK_KEY ?? '' });await pb.passes.remove('0193a1b2-7c00-7000-8000-0000000000c1', { message: 'Refunded' });Undo it with restore.
Replace the links
curl -X POST "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/rotate-link" \ -H "Authorization: Bearer $PASSBOOK_KEY"import { PassBook } from '@passbook/sdk';const pb = new PassBook({ apiKey: process.env.PASSBOOK_KEY ?? '' });// The old link stops working.const pass = await pb.passes.rotateLink('0193a1b2-7c00-7000-8000-0000000000c1');console.log(pass.publicUrl);The old downloadUrl and publicUrl stop working; the new ones are in the answer.
Result
After each call, open the pass's downloadUrl. The preview page shows the state: void, removed or normal. A deleted pass has no page.
Operations
/api/v1/passes/{id}/voidVoid a passPOST/api/v1/passes/{id}/unvoidUnvoid a passPOST/api/v1/passes/{id}/removeRemove from Wallet: publish a voided, expired final versionPOST/api/v1/passes/{id}/restoreUndo a removalPOST/api/v1/passes/{id}/rotate-linkRotate the download linkDEL/api/v1/passes/{id}Delete a pass