> ## Documentation Index
> Fetch the complete documentation index at: https://tapace.lk/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Issue a pass

> Creates a pass from a template for one holder.

The pass is created in the environment of your API key. Send the holder its `distributionUrl` so they can add it. See [Deliver passes](https://tapace.lk/docs/guides/deliver-passes.md).

**Idempotency-Key** `string` *required*

A unique value, such as a UUID, so a retry never issues a second pass. See [Idempotency](https://tapace.lk/docs/idempotency.md).

**templateId** `string` *required*

The template to issue from, for example `tmpl_Q4vN8xT2mLr7KpZs3Wd1`. Archived templates can't issue passes.

**fieldValues** `object`

Values for the template's per-pass fields, keyed by field key. Each value is a string or a number. Every key in the template's `requiredFields` must be included.

**holderName** `string`

The holder's name. Used to find the pass in the dashboard.

**holderEmail** `string`

The holder's email address. Used to find the pass in the dashboard.

**externalId** `string`

Your own reference for the pass, such as your customer ID, up to 255 characters. It doesn't have to be unique, so one customer can hold several passes. Find passes by it with [`GET /v1/passes?externalId=`](https://tapace.lk/docs/api-reference/passes/list). It never appears on the pass.

**metadata** `object`

Your own key-value pairs, such as `{ "plan": "gold" }`. Up to 50 keys of 1 to 40 characters, each with a non-empty string value of up to 500 characters. It never appears on the pass.

**barcodeValue** `string`

The value encoded in the barcode. Required when the template takes a barcode value for each pass.

**featuredActions** `object`

Links for the template's Featured Actions, the buttons Apple Wallet shows below the pass on iOS 27 and later. Keyed by action key, such as `{ "bookTable": "https://example.com/book/8812" }`. Each link must start with `https://`, or `tel:` for a call action. Every key in the template's `requiredActions` must be included on a pass that uses Apple Wallet. A pass without Apple Wallet ignores this. An action with a link on the template uses that link when you leave it out. An action whose link is the same on every pass can't be set here.

**relevance** `object`

When and where Apple Wallet suggests the pass on the Lock Screen. Each list you send replaces the template's for this pass, and `[]` means none. Lists you leave out use the template's.

**properties**

**locations** `array`

Up to 10 places, each with `latitude`, `longitude` and an optional `message` of up to 120 characters shown when the holder is nearby.

**dates** `array`

Up to 10 time windows, each with a `start` and an `end` as dates and times with a timezone offset, such as `2026-11-02T18:00:00+05:30`. Each window must end after it starts. Only for templates that support Apple Wallet.

**stamps** `integer` (default: 0)

Stamp cards only: the starting stamp count, a whole number from 0 to the card's total, such as `1` for a first-visit stamp. See [Stamp cards](https://tapace.lk/docs/guides/stamp-cards.md).

**points** `number`

Points cards only: the starting balance, with up to 2 decimal places. Defaults to the template's starting balance. A value outside the template's limits is moved to the nearest one. See [Points cards](https://tapace.lk/docs/guides/points-cards.md).

**platforms** `object`

Which wallets to issue for. Each defaults to `true` when the template's [`issuePlatforms`](https://tapace.lk/docs/api-reference/templates/get) offers it. Send `false` to skip a wallet. Sending `true` for a wallet the template doesn't offer returns `400`.

**properties**

**apple** `boolean`

Issue for Apple Wallet.

**google** `boolean`

Issue for Google Wallet.

**revision** `integer`

A specific template revision to issue from. Defaults to the latest.

**certificateId** `string`

The Apple certificate to sign with. Defaults to the one chosen in the template's settings.

**googleIssuerId** `string`

The Google Wallet issuer to use. Defaults to the one chosen in the template's settings.

### Response

Returns the new [pass](https://tapace.lk/docs/api-reference/passes/get.md) with status `201`.

### Errors

| Status | When |
| - | - |
| `400` | A field key is unknown, a required field is missing, a value isn't a string or number, a Featured Action is unknown, can't be set per pass, has an invalid link or is required and missing, `relevance` is invalid, `metadata` breaks its limits, `stamps` is outside 0 to the card's total or the template isn't a stamp card, `points` has more than 2 decimal places or the template isn't a points card, the template is archived, the request asks for a wallet the template doesn't offer, or the pass would have no wallet. |
| `404` | The template doesn't exist. |
| `422` | A live pass has no live Apple certificate or Google issuer to sign with. See [Test and live](https://tapace.lk/docs/environments.md). |

```bash cURL theme={null}
curl https://api.tapace.lk/v1/passes \
  -H "Authorization: Bearer $TAPACE_API_KEY" \
  -H "Idempotency-Key: 6f1c2b7e-3b1a-4c9e-9d8a-3f8c5b1d9e2a" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_Q4vN8xT2mLr7KpZs3Wd1",
    "holderName": "Nimal Perera",
    "holderEmail": "nimal@example.com",
    "externalId": "cus_8812",
    "metadata": { "plan": "gold" },
    "fieldValues": {
      "memberName": "Nimal Perera",
      "points": 120
    }
  }'
```

```json 201 theme={null}
{
  "object": "pass",
  "id": "pass_7hGk2LmQ9xVt4RnB8cYe",
  "shortId": "6BkJLsso1xyB",
  "templateId": "tmpl_Q4vN8xT2mLr7KpZs3Wd1",
  "templateName": "Gold membership",
  "templateRevision": 3,
  "environment": "test",
  "status": "active",
  "source": "api",
  "holderName": "Nimal Perera",
  "holderEmail": "nimal@example.com",
  "externalId": "cus_8812",
  "metadata": { "plan": "gold" },
  "platforms": { "apple": true, "google": true },
  "signing": {
    "appleCertificateId": "demo",
    "applePassTypeIdentifier": null,
    "googleIssuerId": "demo"
  },
  "fieldValues": { "memberName": "Nimal Perera", "points": 120 },
  "featuredActions": {},
  "relevance": null,
  "distributionUrl": "https://tapace.lk/p/6BkJLsso1xyB",
  "appleDownloadUrl": "https://tapace.lk/p/6BkJLsso1xyB/apple",
  "googleSaveUrl": "https://tapace.lk/p/6BkJLsso1xyB/google",
  "presence": {
    "apple": { "activeDevices": 0 },
    "google": { "observedState": "unknown" }
  },
  "createdAt": "2026-10-13T10:00:00.000Z",
  "updatedAt": "2026-10-13T10:00:00.000Z",
  "voidedAt": null
}
```

```json 400 theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "Field \"Member name\" is required."
  },
  "requestId": "req_8f3a2c1d9e7b6a54"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.