---
title: "Issue multiple gift cards"
method: POST
path: "/v2/giftcards/programs/{programId}/cards/bulk"
tags: ["Gift Cards"]
---

# Issue multiple gift cards

`POST /v2/giftcards/programs/{programId}/cards/bulk`

### Bulk Issue Gift Cards

Issues multiple gift cards in a single request. For counts up to the sync
threshold (`gift_card_bulk_issue_sync_threshold`, default 50) the cards are
created synchronously and returned immediately. For larger batches the request
is accepted asynchronously and a task ID is returned for polling.

**Issuance modes**:
- `count` (integer) — count-only: cards have no recipient data; a CSV download
  link is returned so the merchant can distribute the numbers.
- `recipients` (list) — per-recipient: each card is optionally pre-populated
  with the given customer info and a notification is dispatched.

**Path Parameters**:
- `programId`: MongoDB ObjectId of the loyalty program

**Request Body** (`BulkIssueGiftCardRequest`):
- `initialValue`: Starting balance (0.01 – 10,000.00)
- `isPhysical`: `true` for physical cards
- `designTemplate`: Optional design-template slug
- `expiresAt`: Optional explicit expiry; defaults to +365 days
- `count` **or** `recipients`: Mutually exclusive

**Response (sync ≤ threshold)**:
- HTTP 201 with `BulkIssuanceSyncResponse`

**Response (async > threshold)**:
- HTTP 202 with `BulkIssuanceAsyncResponse` (`taskId`, `status`)

**Idempotency**:
- Pass `Idempotency-Key` header to make the request safely retryable.

## Path parameters

- `programId` string, required

## Query parameters

- `cardId` string

## Headers

- `idempotency-key` string, nullable
- `X-Eposn-Customer-Token` string, nullable
- `X-Eposn-Merchant-Token` string, nullable

## Request body

- BulkIssueGiftCardRequest
  - `initialValue` union, required
    - number
    - string
  - `isPhysical` boolean
  - `designTemplate` string, nullable
  - `expiresAt` string, date-time, nullable
  - `count` integer, nullable
  - `recipients` BulkIssueRecipient[], nullable
    - `customerEmail` string, email, nullable
    - `customerPhone` string, phone, nullable
    - `customerName` string, nullable
    - `senderName` string, nullable
    - `customMessage` string, nullable

## Response `201`

Successful Response

- union
  - BulkIssuanceSyncResponse
    - `issuedCount` integer, required
    - `cards` BulkIssuedCardSummary[], required
      - `id` string, required
      - `cardNumber` string, required
      - `lastFourDigits` string, required
    - `csvDownloadUrl` string, nullable
    - `failedCount` integer, nullable
  - BulkIssuanceAsyncResponse
    - `taskId` string, required
    - `status` string

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/loyalty/apis/loyaltydog.md) · [All operations](https://skmtc.net/loyalty/apis/loyaltydog/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/loyalty/loyaltydog/versions/42b7b22af2b6/schema)