Resource methods

Use the resource properties on your TapAce client to call the API. The tables below describe the methods implemented in SDK 0.1.0; TypeScript types are exported from @tapace/node. In these signatures, options? means { idempotencyKey?: string }. Results are promises. ListResponse<T> contains object: "list", data, hasMore and nextCursor. There is no automatic page iterator.

Passes

Method on `tapace.passes`	Result	Input
`create(params, options?)`	`Pass`	`templateId`; optional holder, fields, platforms, metadata, loyalty balance and signing overrides.
`issue(params, options?)`	`Pass`	Alias of `create`.
`retrieve(id)`	`PassDetail`	Pass ID.
`list(params?)`	`ListResponse<Pass>`	`cursor`, `limit`, `templateId`, `status`, `source`, `externalId`, `search`.
`update(id, params, options?)`	`PassUpdateResult`	`fieldValues`, `featuredActions`, `relevance`, `stamps`, `points`, `notificationMode`, `externalId`, `metadata`.
`addStamps(id, params, options?)`	`PassUpdateResult`	`add` and optional `notificationMode`.
`addPoints(id, params, options?)`	`PassUpdateResult`	`add` and optional `notificationMode`.
`listUpdates(id, params?)`	`ListResponse<PassUpdate>`	`cursor`, `limit`.
`retrieveUpdate(id, updateId)`	`PassUpdate`	Pass ID and update ID.
`void(id, options?)`	`PassDetail`	Permanently voids the pass using `POST /v1/passes/:id/void`.

PassUpdateResult contains pass and update. The update can be null when no wallet-visible change occurred. See pass issuance, updates, stamps and points for field rules.

void() calls POST /v1/passes/:id/void and permanently voids a pass. archive() calls POST /v1/templates/:id/archive. DELETE on those resource IDs deletes data and is a separate operation. Do not replace void or archive with a raw DELETE request.

The SDK has no dedicated pass-delete, template-delete, expiring-download-link or template-pass-erasure methods.

Templates, events and signing

Method on `tapace.templates`	Result	Input
`retrieve(id)`	`Template`	Template ID; returns its definition when provided by the API.
`list(params?)`	`ListResponse<Template>`	`cursor`, `limit`, `type`, `archived`.
`update(id, params, options?)`	`Template`	`expectedRevision`, optional `name`, `definition` and `issuePlatforms`.
`duplicate(id, params?, options?)`	`Template`	Optional `name`.
`archive(id, options?)`	`Template`	Archives the template using `POST /v1/templates/:id/archive`.
`getEvent(templateId)`	`TemplateEvent`	Event ticket template ID.
`updateEvent(templateId, params, options?)`	`TemplateEventUpdate`	Complete `event` object and optional `notificationMode`.
`getSigning(id)`	`TemplateSigning`	Template ID, for the key’s environment.
`updateSigning(id, params, options?)`	`TemplateSigning`	`appleCertificateId` and/or `googleIssuerId`; types allow `null`.

Always send expectedRevision when updating a template. A definition replaces the current definition; retrieving, editing and saving preserves fields you want to keep. If the revision is stale, retrieve the template again and review the change before resubmitting. See Update a template. Templates expose issuePlatforms. To change wallet availability for new passes, include issuePlatforms: { apple: boolean, google: boolean } in templates.update, along with the required expectedRevision. Both wallet choices are required when supplying the object. Existing passes keep their wallets. Event details are shared across test and live. Send event: {} to clear them. The SDK input requires an object; a retrieved event can still be null when no details are stored. See event details.

Google event sync entries expose environment, a nullable issuerId, status “updated” or “failed”, and an optional error. They do not declare a classId. PUT event/signing requests carry an SDK key, but do not currently provide stored-response replay. Reconcile their current state before retrying.

Deployments

Method on `tapace.deployments`	Result	Input
`create(templateId, params?, options?)`	`Deployment`	`notificationMode`, `appleText`, `googleTitle`, `googleBody`.
`list(templateId, params?)`	`ListResponse<Deployment>`	`cursor`, `limit`.
`retrieve(id)`	`Deployment`	Deployment ID.
`listResults(id, params?)`	`ListResponse<PassDeploymentResult>`	`cursor`, `limit`, `status`.

Creating a deployment starts asynchronous work. Fetch its status and results rather than treating the first response as completed wallet delivery. See Deploy a template.

Notifications

Method on `tapace.notifications`	Result	Input
`createForPass(passId, params, options?)`	`Notification`	Message fields and optional schedule.
`listForPass(passId, params?)`	`ListResponse<Notification>`	`cursor`, `limit`.
`createForTemplate(templateId, params, options?)`	`Notification`	Message fields and optional schedule.
`listForTemplate(templateId, params?)`	`ListResponse<Notification>`	`cursor`, `limit`.
`retrieve(id)`	`Notification`	Notification ID.
`update(id, params, options?)`	`Notification`	Complete replacement message and schedule for a scheduled notification.
`cancel(id, options?)`	`Notification`	Scheduled notification ID.

Message fields are appleText, googleTitle and googleBody, with scheduledFor for scheduling. Creation accepts ComposeNotificationParams with an optional schedule. Editing accepts UpdateNotificationParams, which requires a non-null scheduledFor string. Required text depends on the target wallets. See Send to a pass, Send to a template and Update a scheduled notification.

Assets

Method on `tapace.assets`	Result	Input
`upload(params, options?)`	`Asset`	`slot`, `data`, optional `contentType`.
`retrieve(id)`	`Asset`	Asset ID.
`download(id)`	`AssetContent`	Returns `bytes: Uint8Array` and `contentType`.

Upload data can be a Buffer, Uint8Array, base64 string or base64 data URL. The SDK converts bytes to base64. For a data URL, it infers MIME type unless you supply one. See asset limits and slots.

import { readFile, writeFile } from "node:fs/promises";

// Using an initialized tapace client:
const asset = await tapace.assets.upload({
  slot: "logo",
  contentType: "image/png",
  data: await readFile("./logo.png"),
});
const downloaded = await tapace.assets.download(asset.id);
await writeFile("./downloaded-logo", downloaded.bytes);

Account and wallet signers

tapace.me.retrieve() returns AccountInfo with organizationId and environment. tapace.walletSigners.list() returns WalletSigners: environment, apple and google signer options. Each option exposes ready and an optional reason. Template signing assignments contain appleCertificateId and googleIssuerId. See List wallet signers, Get template signing and Update template signing for the HTTP contracts. Signing choices affect new passes; existing passes retain their issued signing identity. The demo choice is test-only. Clearing a live selection with null is allowed, but test mode rejects null.

Page through results

// Using an initialized tapace client:
let cursor: string | undefined;
do {
  const page = await tapace.passes.list({ limit: 50, cursor });
  for (const pass of page.data) console.log(pass.id);
  if (!page.hasMore || !page.nextCursor) break;
  cursor = page.nextCursor;
} while (true);

The SDK trusts response JSON as the declared type. TypeScript autocomplete is not runtime schema validation.

Credit loyalty balances

Use a stamp-card pass for addStamps and a points-card pass for addPoints. These operations add to the existing balance. To set a balance directly, use passes.update with stamps or points. Limits and rounding are described in the stamp and points guides.

import { TapAce, idempotencyKey } from "@tapace/node";

export async function creditSale(
  tapace: TapAce,
  saleId: string,
  stampPassId: string,
  pointsPassId: string,
) {
  const stamps = await tapace.passes.addStamps(
    stampPassId,
    { add: 2, notificationMode: "silent" },
    { idempotencyKey: idempotencyKey("sale-stamps", saleId) },
  );
  const points = await tapace.passes.addPoints(
    pointsPassId,
    { add: 25, notificationMode: "silent" },
    { idempotencyKey: idempotencyKey("sale-points", saleId) },
  );
  return { stamps, points };
}

Save the sale and exact award details before calling this function. Each call is a separate API operation; the two awards are not an atomic transaction. If the second call fails, retry with the same saved IDs and bodies so the first award can replay instead of crediting twice. Persist completion for each award and respect the key retention window.

Send a message

Use notifications when you want to send text rather than change a balance or field. A pass notification appears in Apple Wallet’s Message for you field; a template notification uses Announcements.

import { TapAce, idempotencyKey } from "@tapace/node";

export async function notifyHolder(tapace: TapAce, passId: string, messageId: string) {
  const notification = await tapace.notifications.createForPass(
    passId,
    {
      appleText: "Your table is ready.",
      googleTitle: "Table ready",
      googleBody: "Please come to the front desk.",
    },
    { idempotencyKey: idempotencyKey("table-ready-message", messageId) },
  );
  return tapace.notifications.retrieve(notification.id);
}

The immediate response can still be queued or sending. Save notification.id and retrieve it later to inspect delivery. A new message needs a new saved operation ID. On Apple, resending identical visible text does not create another alert and is rejected by the API.

Deploy a changed template

Saving a template definition does not migrate existing passes. Create a deployment after saving the intended revision, then inspect its status and per-pass results.

import { TapAce, idempotencyKey } from "@tapace/node";

export async function deployDesign(tapace: TapAce, templateId: string, operationId: string) {
  const deployment = await tapace.deployments.create(
    templateId,
    { notificationMode: "silent" },
    { idempotencyKey: idempotencyKey("design-deployment", operationId) },
  );
  return {
    deployment: await tapace.deployments.retrieve(deployment.id),
    results: await tapace.deployments.listResults(deployment.id, { limit: 50 }),
  };
}

This reads the current status and first result page, not a completion guarantee. Continue checking the saved deployment ID from your job or application, and paginate results using nextCursor.

Getting started

Basics

Guides

Node.js SDK

API keys

Passes

Loyalty cards

Notifications

Templates

Wallet signing

Deployments

Assets

Resource methods

Passes

Templates, events and signing

Deployments

Notifications

Assets

Account and wallet signers

Page through results

Credit loyalty balances

Send a message

Deploy a changed template

​Passes

​Templates, events and signing

​Deployments

​Notifications

​Assets

​Account and wallet signers

​Page through results

​Credit loyalty balances

​Send a message

​Deploy a changed template

Passes

Templates, events and signing

Deployments

Notifications

Assets

Account and wallet signers

Page through results

Credit loyalty balances

Send a message

Deploy a changed template