Issue multiple gift cards

curl --request POST \
  --url https://api.loyalty.dog/v2/giftcards/programs/{programId}/cards/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "initialValue": 5000.005,
  "isPhysical": false,
  "designTemplate": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z",
  "count": 2,
  "recipients": [
    {
      "customerEmail": "[email protected]",
      "customerPhone": "<string>",
      "customerName": "<string>",
      "senderName": "<string>",
      "customMessage": "<string>"
    }
  ]
}
'

{
  "issuedCount": 123,
  "cards": [
    {
      "id": "<string>",
      "cardNumber": "<string>",
      "lastFourDigits": "<string>"
    }
  ],
  "csvDownloadUrl": "<string>",
  "failedCount": 123
}

Gift Cards

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.

POST

giftcards

programs

{programId}

cards

bulk

Issue multiple gift cards

curl --request POST \
  --url https://api.loyalty.dog/v2/giftcards/programs/{programId}/cards/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "initialValue": 5000.005,
  "isPhysical": false,
  "designTemplate": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z",
  "count": 2,
  "recipients": [
    {
      "customerEmail": "[email protected]",
      "customerPhone": "<string>",
      "customerName": "<string>",
      "senderName": "<string>",
      "customMessage": "<string>"
    }
  ]
}
'

{
  "issuedCount": 123,
  "cards": [
    {
      "id": "<string>",
      "cardNumber": "<string>",
      "lastFourDigits": "<string>"
    }
  ],
  "csvDownloadUrl": "<string>",
  "failedCount": 123
}

Authorizations

Authorization

string

header

required

JWT access token obtained from POST /v2/token.

Headers

idempotency-key

string | null

X-Eposn-Customer-Token

string | null

X-Eposn-Merchant-Token

string | null

Path Parameters

programId

string | null

required

Required string length: 24

Pattern: ^[0-9a-f]{24}$

Example:

"5eb7cf5a86d9755df3a6c593"

Query Parameters

cardId

string | null

Required string length: 24

Pattern: ^[0-9a-f]{24}$

Example:

"5eb7cf5a86d9755df3a6c593"

Body

application/json

initialValue

required

Required range: 0.01 <= x <= 10000

isPhysical

boolean

default:false

designTemplate

string | null

Maximum string length: 100

expiresAt

string<date-time> | null

count

integer | null

Required range: x >= 1

recipients

BulkIssueRecipient · object[] | null

Show child attributes

Response

Successful Response

BulkIssuanceSyncResponse
BulkIssuanceAsyncResponse

issuedCount

integer

required

cards

BulkIssuedCardSummary · object[]

required

Show child attributes

csvDownloadUrl

string | null

failedCount

integer | null

Getcustomerconsolidatablemerchants Poll async bulk issuance task