# Bundles

Passes · PassBook API reference. Authenticate with `Authorization: Bearer $PASSBOOK_KEY`.

## List bundles {#list}

`GET /api/v1/bundles`

Scopes: `passes:read`. SDK name: `pb.bundles.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string · max 512 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |
| `passId` | query | string · max 64 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BUNDLE_DUPLICATE_PASS` |  | List each pass id once. |
| `BUNDLE_EMPTY` |  | Add at least one pass to the bundle. |
| `BUNDLE_MODE_MISMATCH` |  | Put only passes of the bundle's mode in it. |
| `BUNDLE_NOT_FOUND` |  | Check the id with GET /api/v1/bundles. |
| `BUNDLE_TOO_MANY` |  | Send at most 10 passes per bundle. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `LINK_NOT_FOUND` |  | Request a fresh link, for example with POST /api/v1/bundles/{id}/rotate-link. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X GET "https://passbook.mobile/api/v1/bundles" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Create a bundle of up to 10 passes {#create}

`POST /api/v1/bundles`

Scopes: `passes:write`. SDK name: `pb.bundles.create`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | body | string · max 64 | yes |  |
| `passIds` | body | string · max 64[] | yes |  |
| `name` | body | string · max 80 | yes |  |
| `holderEmail` | body | string · max 254 |  |  |
| `sendEmail` | body | boolean |  |  |

Returns `201`.

| Code | Status | Fix |
| --- | --- | --- |
| `BUNDLE_DUPLICATE_PASS` |  | List each pass id once. |
| `BUNDLE_EMPTY` |  | Add at least one pass to the bundle. |
| `BUNDLE_MODE_MISMATCH` |  | Put only passes of the bundle's mode in it. |
| `BUNDLE_NOT_FOUND` |  | Check the id with GET /api/v1/bundles. |
| `BUNDLE_TOO_MANY` |  | Send at most 10 passes per bundle. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `LINK_NOT_FOUND` |  | Request a fresh link, for example with POST /api/v1/bundles/{id}/rotate-link. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/bundles" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "passIds": [
    "0193a1b2-7c00-7000-8000-0000000000c1"
  ],
  "name": "Example"
}'
```

## One bundle {#retrieve}

`GET /api/v1/bundles/{id}`

Scopes: `passes:read`. SDK name: `pb.bundles.retrieve`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BUNDLE_DUPLICATE_PASS` |  | List each pass id once. |
| `BUNDLE_EMPTY` |  | Add at least one pass to the bundle. |
| `BUNDLE_MODE_MISMATCH` |  | Put only passes of the bundle's mode in it. |
| `BUNDLE_NOT_FOUND` |  | Check the id with GET /api/v1/bundles. |
| `BUNDLE_TOO_MANY` |  | Send at most 10 passes per bundle. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `LINK_NOT_FOUND` |  | Request a fresh link, for example with POST /api/v1/bundles/{id}/rotate-link. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X GET "https://passbook.mobile/api/v1/bundles/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Delete the bundle and revoke its link {#delete}

`DELETE /api/v1/bundles/{id}`

Scopes: `passes:write`. SDK name: `pb.bundles.delete`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BUNDLE_DUPLICATE_PASS` |  | List each pass id once. |
| `BUNDLE_EMPTY` |  | Add at least one pass to the bundle. |
| `BUNDLE_MODE_MISMATCH` |  | Put only passes of the bundle's mode in it. |
| `BUNDLE_NOT_FOUND` |  | Check the id with GET /api/v1/bundles. |
| `BUNDLE_TOO_MANY` |  | Send at most 10 passes per bundle. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `LINK_NOT_FOUND` |  | Request a fresh link, for example with POST /api/v1/bundles/{id}/rotate-link. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X DELETE "https://passbook.mobile/api/v1/bundles/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Email the bundle link {#sendEmail}

`POST /api/v1/bundles/{id}/send-email`

Scopes: `passes:write`. Idempotent with an `Idempotency-Key` header. SDK name: `pb.bundles.sendEmail`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `Idempotency-Key` | header | string · max 200 |  | 1 to 200 characters. A retry with the same key and body returns the first result. |
| `to` | body | string · max 254 |  |  |

Returns `202`.

| Code | Status | Fix |
| --- | --- | --- |
| `BUNDLE_DUPLICATE_PASS` |  | List each pass id once. |
| `BUNDLE_EMPTY` |  | Add at least one pass to the bundle. |
| `BUNDLE_MODE_MISMATCH` |  | Put only passes of the bundle's mode in it. |
| `BUNDLE_NOT_FOUND` |  | Check the id with GET /api/v1/bundles. |
| `BUNDLE_TOO_MANY` |  | Send at most 10 passes per bundle. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `LINK_NOT_FOUND` |  | Request a fresh link, for example with POST /api/v1/bundles/{id}/rotate-link. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/bundles/0193a1b2-7c00-7000-8000-0000000000e1/send-email" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Replace the link; the old one stops working {#rotateLink}

`POST /api/v1/bundles/{id}/rotate-link`

Scopes: `passes:write`. SDK name: `pb.bundles.rotateLink`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `BUNDLE_DUPLICATE_PASS` |  | List each pass id once. |
| `BUNDLE_EMPTY` |  | Add at least one pass to the bundle. |
| `BUNDLE_MODE_MISMATCH` |  | Put only passes of the bundle's mode in it. |
| `BUNDLE_NOT_FOUND` |  | Check the id with GET /api/v1/bundles. |
| `BUNDLE_TOO_MANY` |  | Send at most 10 passes per bundle. |
| `DELIVERY_STALE` |  | Review the recipient and try again. |
| `EMAIL_INVALID` |  | Send a valid address in the email field. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `LINK_NOT_FOUND` |  | Request a fresh link, for example with POST /api/v1/bundles/{id}/rotate-link. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `NO_RECIPIENT` |  | Set the holder's email with PATCH /api/v1/passes/{id}, then send again. |
| `ORG_REQUIRED` |  | Send orgId with the request, or use a key scoped to one organization. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RECIPIENT_NOT_HOLDER` |  | Send to the holder's email, or change it with PATCH /api/v1/passes/{id}. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

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