Issue multiple gift cards

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.