Pass lifecycle

Void, remove, delete

Markdown

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.

Pass lifecycleA pass is Active, Voided, Removed or Deleted. void and unvoid move it between Active and Voided. remove and restore move it between Active and Removed. DELETE ends it from any state. update, refresh, renew, new-code and rotate-link leave it Active.Voidedscans refusedActiveupdate, refresh, renewRemovedin Expired passesDeletedrecord gone, Wallet keeps the pass and sends it no updatesvoidunvoidremoverestoreDELETE, from any state

Ending a pass

CallMoves it toUndoWhat it does
voidVoidedunvoidMarks the pass void and republishes it. Scans are refused.
removeRemovedrestorePublishes a last version that is voided and expired, so Wallet moves it to Expired passes. The record stays. message shows on the lock screen.
DELETEDeletednoneDeletes 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

CallWhat changesOld value
updateFields, as a new version.Kept in the version list.
refreshRebuilds the pass from its connection and pushes it again.Replaced.
renewThe pass's term.Replaced.
new-codeThe scan code. Same serial and holder.Stops scanning. Three a pass an hour.
rotate-linkThe download and public links. The pass itself is unchanged.Stops working.
bulk-reissueRebuilds 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

Void a pass
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);
Copy as
Open in consoleOpens the console with this request filled in.
Undo a void
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);
Copy as
Open in consoleOpens the console with this request filled in.

The pass answers with status: "voided", then "active". Paste the pass id into the path.

Remove and restore

Remove a pass from Wallet
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' });
Copy as
Open in consoleOpens the console with this request filled in.

Undo it with restore.

Replace a pass link
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);
Copy as
Open in consoleOpens the console with this request filled in.

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