> ## 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.

# Resource methods

> Find TapAce SDK methods, input options and result types for passes, templates, events, deployments, notifications, assets, wallet signers and account details.

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](https://tapace.lk/docs/api-reference/passes/issue.md), [updates](https://tapace.lk/docs/api-reference/passes/update.md), [stamps](https://tapace.lk/docs/guides/stamp-cards.md) and [points](https://tapace.lk/docs/guides/points-cards.md) for field rules.

> [!NOTE]
>
> `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](https://tapace.lk/docs/api-reference/templates/update.md).

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](https://tapace.lk/docs/api-reference/templates/get-event.md).

> [!NOTE]
>
> 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](https://tapace.lk/docs/api-reference/deployments/create.md).

## 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](https://tapace.lk/docs/api-reference/notifications/send-to-pass.md), [Send to a template](https://tapace.lk/docs/api-reference/notifications/send-to-template.md) and [Update a scheduled notification](https://tapace.lk/docs/api-reference/notifications/update.md).

## 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](https://tapace.lk/docs/api-reference/assets/upload.md).

```typescript theme={null}
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](https://tapace.lk/docs/api-reference/wallet-signers/list.md), [Get template signing](https://tapace.lk/docs/api-reference/templates/get-signing.md) and [Update template signing](https://tapace.lk/docs/api-reference/templates/update-signing.md) 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

```typescript theme={null}
// 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](https://tapace.lk/docs/guides/stamp-cards.md) and [points](https://tapace.lk/docs/guides/points-cards.md) guides.

```typescript theme={null}
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](https://tapace.lk/docs/sdk/node/reliability.md).

## 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**.

```typescript theme={null}
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.

```typescript theme={null}
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`.


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