Consolidategiftcards

curl --request POST \
  --url https://api.loyalty.dog/v2/giftcards/programs/{programId}/consolidate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardNumbers": [
    "<string>"
  ],
  "merchantId": "5eb7cf5a86d9755df3a6c593",
  "customerEmail": "[email protected]",
  "customerName": "<string>",
  "senderName": "<string>",
  "referenceId": "<string>",
  "description": "<string>",
  "isPhysical": false,
  "designTemplate": "<string>",
  "customMessage": "<string>"
}
'

{
  "success": true,
  "message": "<string>",
  "newCard": {
    "id": "5eb7cf5a86d9755df3a6c593",
    "cardNumber": "<string>",
    "balance": "<string>",
    "initialValue": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "activatedAt": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z",
    "suspendedReason": "<string>",
    "suspendedUntil": "2023-11-07T05:31:56Z",
    "suspendedAt": "2023-11-07T05:31:56Z",
    "customerId": "5eb7cf5a86d9755df3a6c593",
    "customerEmail": "<string>",
    "customerPhone": "<string>",
    "customerName": "<string>",
    "merchantId": "5eb7cf5a86d9755df3a6c593",
    "isPhysical": true,
    "designTemplate": "<string>",
    "customMessage": "<string>",
    "lastFourDigits": "<string>",
    "programId": "5eb7cf5a86d9755df3a6c593",
    "card": {
      "serialNumber": "<string>",
      "passTypeIdentifier": "<string>",
      "url": "<string>"
    },
    "senderName": "<string>",
    "merchantName": "<string>",
    "deliverAt": "2023-11-07T05:31:56Z",
    "delivered": false
  },
  "voidedCards": [
    "<string>"
  ],
  "totalConsolidatedAmount": "<string>",
  "consolidationTransactions": [
    "<string>"
  ],
  "referenceId": "<string>"
}

Gift Cards

Consolidategiftcards

Consolidates multiple ACTIVE gift cards from the same program and customer into a single new active card with the combined balance.

Performs validation (2–10 unique cards, all ACTIVE, positive balances, same customer, total ≤ $10,000), acquires per-card locks to prevent concurrent modifications, creates a new card with a cryptographically generated number and security code, voids source cards (setting their balances to zero), and records consolidation transactions inside an atomic database transaction.

Returns: ConsolidateResponse: Details of the consolidation including newCard (the created gift card), voidedCards (IDs of source cards), totalConsolidatedAmount, consolidationTransactions (transaction IDs), and an informational message.

Idempotency Scope: Keys are scoped to programId + consolidate + sorted source card ids. Reusing the same key for a different source-card set is treated as a fresh operation.

POST

giftcards

programs

{programId}

consolidate

Consolidategiftcards

curl --request POST \
  --url https://api.loyalty.dog/v2/giftcards/programs/{programId}/consolidate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardNumbers": [
    "<string>"
  ],
  "merchantId": "5eb7cf5a86d9755df3a6c593",
  "customerEmail": "[email protected]",
  "customerName": "<string>",
  "senderName": "<string>",
  "referenceId": "<string>",
  "description": "<string>",
  "isPhysical": false,
  "designTemplate": "<string>",
  "customMessage": "<string>"
}
'

{
  "success": true,
  "message": "<string>",
  "newCard": {
    "id": "5eb7cf5a86d9755df3a6c593",
    "cardNumber": "<string>",
    "balance": "<string>",
    "initialValue": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "activatedAt": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z",
    "suspendedReason": "<string>",
    "suspendedUntil": "2023-11-07T05:31:56Z",
    "suspendedAt": "2023-11-07T05:31:56Z",
    "customerId": "5eb7cf5a86d9755df3a6c593",
    "customerEmail": "<string>",
    "customerPhone": "<string>",
    "customerName": "<string>",
    "merchantId": "5eb7cf5a86d9755df3a6c593",
    "isPhysical": true,
    "designTemplate": "<string>",
    "customMessage": "<string>",
    "lastFourDigits": "<string>",
    "programId": "5eb7cf5a86d9755df3a6c593",
    "card": {
      "serialNumber": "<string>",
      "passTypeIdentifier": "<string>",
      "url": "<string>"
    },
    "senderName": "<string>",
    "merchantName": "<string>",
    "deliverAt": "2023-11-07T05:31:56Z",
    "delivered": false
  },
  "voidedCards": [
    "<string>"
  ],
  "totalConsolidatedAmount": "<string>",
  "consolidationTransactions": [
    "<string>"
  ],
  "referenceId": "<string>"
}

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

cardNumbers

string[]

required

Required array length: 2 - 10 elements

merchantId

string

required

Required string length: 24

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

Example:

"5eb7cf5a86d9755df3a6c593"

customerEmail

string<email> | null

customerName

string | null

Maximum string length: 255

senderName

string | null

Maximum string length: 255

referenceId

string | null

Maximum string length: 100

description

string | null

Maximum string length: 500

isPhysical

boolean

default:false

designTemplate

string | null

Maximum string length: 100

customMessage

string | null

Maximum string length: 500

Response

Successful Response

success

boolean

required

message

string

required

newCard

GiftCardResponse · object

required

Show child attributes

voidedCards

string[]

required

totalConsolidatedAmount

string

required

consolidationTransactions

string[]

required

referenceId

string | null

required

Checkgiftcardbalance Getgiftcardtransactions