Issue a pass

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
    }
  }'

{
  "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
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "Field \"Member name\" is required."
  },
  "requestId": "req_8f3a2c1d9e7b6a54"
}

POST

passes

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
    }
  }'

{
  "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
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "Field \"Member name\" is required."
  },
  "requestId": "req_8f3a2c1d9e7b6a54"
}

The pass is created in the environment of your API key. Send the holder its distributionUrl so they can add it. See Deliver passes.

string

required

A unique value, such as a UUID, so a retry never issues a second pass. See Idempotency.

string

required

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

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.

string

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

string

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

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=. It never appears on the pass.

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.

string

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

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.

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.

Show properties

array

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

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.

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.

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.

object

Which wallets to issue for. Each defaults to true when the template’s issuePlatforms offers it. Send false to skip a wallet. Sending true for a wallet the template doesn’t offer returns 400.

Show properties

boolean

Issue for Apple Wallet.

boolean

Issue for Google Wallet.

integer

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

string

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

string

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

Response

Returns the new pass 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.

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
    }
  }'

{
  "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
}

{
  "error": {
    "type": "invalid_request_error",
    "message": "Field \"Member name\" is required."
  },
  "requestId": "req_8f3a2c1d9e7b6a54"
}

Getting started

Basics

Guides

Node.js SDK

API keys

Passes

Loyalty cards

Notifications

Templates

Wallet signing

Deployments

Assets

Response

Errors

​Response

​Errors

Response

Errors