# Pass lifecycle

Void, remove, delete. Runs in your test sandbox: nothing is issued, every pass is a test preview. Authenticate with `Authorization: Bearer $PASSBOOK_KEY`. Ids in the examples are placeholders: use the ids your sandbox returns.

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.

```mermaid
stateDiagram-v2
  Active --> Voided: void
  Voided --> Active: unvoid
  Active --> Removed: remove
  Removed --> Active: restore
  Active --> Deleted: DELETE
  Voided --> Deleted: DELETE
  Removed --> Deleted: DELETE
```

## 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

**Void a pass**

```sh
curl -X POST "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/void" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

```ts
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);
```

**Undo a void**

```sh
curl -X POST "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/unvoid" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

```ts
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

**Remove a pass from Wallet**

```sh
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"
}'
```

```ts
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](https://passbook.mobile/developers/reference/passes#restore).

## Replace the links

**Replace a pass link**

```sh
curl -X POST "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/rotate-link" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

```ts
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

- [POST /api/v1/passes/{id}/void](https://passbook.mobile/developers/reference/passes#void): Void a pass (`pb.passes.void`)
- [POST /api/v1/passes/{id}/unvoid](https://passbook.mobile/developers/reference/passes#unvoid): Unvoid a pass (`pb.passes.unvoid`)
- [POST /api/v1/passes/{id}/remove](https://passbook.mobile/developers/reference/passes#remove): Remove from Wallet: publish a voided, expired final version (`pb.passes.remove`)
- [POST /api/v1/passes/{id}/restore](https://passbook.mobile/developers/reference/passes#restore): Undo a removal (`pb.passes.restore`)
- [POST /api/v1/passes/{id}/rotate-link](https://passbook.mobile/developers/reference/passes#rotateLink): Rotate the download link (`pb.passes.rotateLink`)
- [DELETE /api/v1/passes/{id}](https://passbook.mobile/developers/reference/passes#delete): Delete a pass (`pb.passes.delete`)

More guides: https://passbook.mobile/developers/guides
