Issue on purchase

Checkout webhook to pass

Markdown

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.

{  "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"  }}
Open in consoleOpens the console with this request filled in.

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
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
curl -X GET "https://passbook.mobile/api/v1/passes?externalId=order-8841" \  -H "Authorization: Bearer $PASSBOOK_KEY"
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');
Copy as
Open in consoleOpens the console with this request filled in.

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

A sandbox sends no mail. The message lands in the test inbox.

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 when the order changes.

Operations