# Issue on purchase

Checkout webhook to pass. 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.

When an order completes, make one pass for it. Use the order id twice: as `externalId`, so you can find the pass later, and as the `Idempotency-Key`, so a retried webhook never makes a second one.

Your sandbox renders the pass as a test preview. Nothing is signed or sent.

## Create the pass for an order

Send the order id as the key. In the console, the Idempotency-Key chip is on; set it to `order-8841`.

```json
{
  "templateId": "0193a1b2-7c00-7000-8000-0000000000b1",
  "externalId": "order-8841",
  "holderEmail": "ada@example.com",
  "input": {
    "eventName": "Harbor Night",
    "venueName": "Harbor Hall",
    "venueRegion": "Cupertino, CA",
    "startsAt": "2030-06-01T19:00:00-07:00",
    "endsAt": "2030-06-01T22:00:00-07:00",
    "attendee": "Ada Example",
    "ticketId": "TICKET-8841"
  }
}
```

The answer is `201` with the pass. Keep its `id`.

## Replay the order

Choose "Run again with the same key". The answer carries the same pass and the header `Idempotent-Replayed: true`. No second pass exists.

The same key with a different body is `422 IDEMPOTENCY_KEY_REUSED`. A repeat while the first call still runs is `409 IDEMPOTENCY_IN_PROGRESS`; wait and send it again.

## Do it in code

**Retry a create without a duplicate**

```ts
import { PassBook } from '@passbook/sdk';

const pb = new PassBook({ apiKey: process.env.PASSBOOK_KEY ?? '' });

// The same key returns the first pass instead of making a second one.
const options = { idempotencyKey: 'order-8841' };
const body = {
  templateId: '0193a1b2-7c00-7000-8000-0000000000b1',
  externalId: 'order-8841',
  input: {
    eventName: 'Harbor Night',
    venueName: 'Harbor Hall',
    venueRegion: 'Cupertino, CA',
    startsAt: '2030-06-01T19:00:00-07:00',
    endsAt: '2030-06-01T22:00:00-07:00',
    attendee: 'Ada Example',
    ticketId: 'TICKET-0002',
  },
};

const first = await pb.passes.create(body, options);
const again = await pb.passes.create(body, options);

console.log(first.id === again.id);
```

Call this from your checkout webhook handler. A retry of the webhook lands on the same pass.

## Find the pass by order

**Find the pass for an order**

```sh
curl -X GET "https://passbook.mobile/api/v1/passes?externalId=order-8841" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

```ts
import { PassBook } from '@passbook/sdk';

const pb = new PassBook({ apiKey: process.env.PASSBOOK_KEY ?? '' });

const page = await pb.passes.list({ externalId: 'order-8841' });

console.log(page.items[0]?.id ?? 'no pass for this order');
```

`items` holds the pass whose `externalId` matches. Filter on it when a refund or a change arrives.

## Email it

Set `sendEmail` with `holderEmail` on create, or send it later. Paste the pass `id` into the path.

**Email a pass**

```sh
curl -X POST "https://passbook.mobile/api/v1/passes/0193a1b2-7c00-7000-8000-0000000000c1/resend-email" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "ada@example.com"
}'
```

```ts
import { PassBook } from '@passbook/sdk';

const pb = new PassBook({ apiKey: process.env.PASSBOOK_KEY ?? '' });

await pb.passes.sendEmail('0193a1b2-7c00-7000-8000-0000000000c1', { to: 'ada@example.com' });
```

A sandbox sends no mail. The message lands in the [test inbox](https://passbook.mobile/developers/reference/test-emails#list).

## Result

Open `downloadUrl` from the create answer. It is the test preview page for the pass: the card as Apple, Google and Samsung would draw it, with no Add button. The pass detail carries `testPreview: true`.

Next: [update a pass](https://passbook.mobile/developers/guides/update-a-pass) when the order changes.

## Operations

- [POST /api/v1/passes](https://passbook.mobile/developers/reference/passes#create): Create a pass (`pb.passes.create`)
- [GET /api/v1/passes](https://passbook.mobile/developers/reference/passes#list): List passes (`pb.passes.list`)
- [POST /api/v1/passes/{id}/resend-email](https://passbook.mobile/developers/reference/passes#sendEmail): Email the pass to the holder (`pb.passes.sendEmail`)
- [GET /api/v1/test-inbox](https://passbook.mobile/developers/reference/test-emails#list): List captured test emails, newest first (`pb.testEmails.list`)

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