---
title: "Consolidategiftcards"
method: POST
path: "/v2/giftcards/programs/{programId}/consolidate"
tags: ["Gift Cards"]
---

# Consolidategiftcards

`POST /v2/giftcards/programs/{programId}/consolidate`

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.

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

- ConsolidateGiftCardsRequest
  - `cardNumbers` string[], required
  - `customerEmail` string, email, nullable
  - `customerName` string, nullable
  - `senderName` string, nullable
  - `merchantId` string, required
  - `referenceId` string, nullable
  - `description` string, nullable
  - `isPhysical` boolean
  - `designTemplate` string, nullable
  - `customMessage` string, nullable

## Response `200`

Successful Response

- ConsolidateResponse
  - `success` boolean, required
  - `message` string, required
  - `newCard` GiftCardResponse, required
    - `id` string, required
    - `cardNumber` string, required
    - `balance` string, required
    - `initialValue` string, required
    - `status` 'pending' | 'active' | 'suspended' | 'expired' | 'voided' | 'depleted', required — Gift card status enumeration.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, nullable, required
    - `activatedAt` string, date-time, nullable, required
    - `expiresAt` string, date-time, required
    - `suspendedReason` string, nullable, required
    - `suspendedUntil` string, date-time, nullable, required
    - `suspendedAt` string, date-time, nullable, required
    - `customerId` string, required
    - `customerEmail` string, nullable, required
    - `customerPhone` string, nullable, required
    - `customerName` string, nullable, required
    - `senderName` string, nullable
    - `merchantId` string, required
    - `merchantName` string, nullable
    - `isPhysical` boolean, required
    - `designTemplate` string, nullable, required
    - `customMessage` string, nullable, required
    - `lastFourDigits` string, required
    - `programId` string, required
    - `deliverAt` string, date-time, nullable
    - `delivered` boolean
    - `card` PassCard, required — The customer card object Attributes: serialNumber (str): The serial number of the customer pass passTypeIdentifier (str): The pass type identifier of the customer pass url (str): The shareable URL of the customer pass
      - `serialNumber` string, required
      - `passTypeIdentifier` string, required
      - `url` string, uri, required
  - `voidedCards` string[], required
  - `totalConsolidatedAmount` string, required
  - `consolidationTransactions` string[], required
  - `referenceId` string, nullable, required

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