> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loyalty.dog/llms.txt
> Use this file to discover all available pages before exploring further.

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



## OpenAPI

````yaml https://api.loyalty.dog/openapi.json post /v2/giftcards/programs/{programId}/consolidate
openapi: 3.1.0
info:
  title: LoyaltyDog
  description: >-

    Welcome to the LoyaltyDog API! This API provides access to our loyalty
    program features, allowing you to integrate with various platforms and
    manage your loyalty data.


    Want to query LoyaltyDog via an AI assistant (Claude, Cursor, Windsurf)? See
    the [MCP Integration guide](https://loyaltydog.ai/playground#mcp).
        
  termsOfService: https://loyalty.dog/loyalty-program-terms-service
  contact:
    name: LoyaltyDog Support
    url: https://loyalty.dog/contact-us
    email: support@loyalty.dog
  version: 1.0.1
servers:
  - url: https://api.loyalty.dog
    description: Production
security:
  - bearerAuth: []
paths:
  /v2/giftcards/programs/{programId}/consolidate:
    post:
      tags:
        - Gift Cards
      summary: Consolidategiftcards
      description: >-
        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.
      operationId: consolidateGiftCards_v2_giftcards_programs__programId__consolidate_post
      parameters:
        - name: programId
          in: path
          required: true
          schema:
            anyOf:
              - $ref: '#/components/schemas/PydanticObjectId'
              - type: 'null'
            title: Programid
        - name: cardId
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/PydanticObjectId'
              - type: 'null'
            title: Cardid
        - name: idempotency-key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Idempotency-Key
        - name: X-Eposn-Customer-Token
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Eposn-Customer-Token
        - name: X-Eposn-Merchant-Token
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Eposn-Merchant-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsolidateGiftCardsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsolidateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PydanticObjectId:
      type: string
      maxLength: 24
      minLength: 24
      pattern: ^[0-9a-f]{24}$
      example: 5eb7cf5a86d9755df3a6c593
    ConsolidateGiftCardsRequest:
      properties:
        cardNumbers:
          items:
            type: string
          type: array
          maxItems: 10
          minItems: 2
          title: Cardnumbers
        customerEmail:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Customeremail
        customerName:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Customername
        senderName:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Sendername
        merchantId:
          $ref: '#/components/schemas/PydanticObjectId'
        referenceId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Referenceid
        description:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Description
        isPhysical:
          type: boolean
          title: Isphysical
          default: false
        designTemplate:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Designtemplate
        customMessage:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Custommessage
      type: object
      required:
        - cardNumbers
        - merchantId
      title: ConsolidateGiftCardsRequest
    ConsolidateResponse:
      properties:
        success:
          type: boolean
          title: Success
        message:
          type: string
          title: Message
        newCard:
          $ref: '#/components/schemas/GiftCardResponse'
        voidedCards:
          items:
            type: string
          type: array
          title: Voidedcards
        totalConsolidatedAmount:
          type: string
          title: Totalconsolidatedamount
        consolidationTransactions:
          items:
            type: string
          type: array
          title: Consolidationtransactions
        referenceId:
          anyOf:
            - type: string
            - type: 'null'
          title: Referenceid
      type: object
      required:
        - success
        - message
        - newCard
        - voidedCards
        - totalConsolidatedAmount
        - consolidationTransactions
        - referenceId
      title: ConsolidateResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GiftCardResponse:
      properties:
        id:
          $ref: '#/components/schemas/PydanticObjectId'
        cardNumber:
          type: string
          title: Cardnumber
        balance:
          type: string
          title: Balance
        initialValue:
          type: string
          title: Initialvalue
        status:
          $ref: '#/components/schemas/GiftCardStatus'
        createdAt:
          type: string
          format: date-time
          title: Createdat
        updatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updatedat
        activatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Activatedat
        expiresAt:
          type: string
          format: date-time
          title: Expiresat
        suspendedReason:
          anyOf:
            - type: string
            - type: 'null'
          title: Suspendedreason
        suspendedUntil:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Suspendeduntil
        suspendedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Suspendedat
        customerId:
          anyOf:
            - $ref: '#/components/schemas/PydanticObjectId'
            - type: 'null'
        customerEmail:
          anyOf:
            - type: string
            - type: 'null'
          title: Customeremail
        customerPhone:
          anyOf:
            - type: string
            - type: 'null'
          title: Customerphone
        customerName:
          anyOf:
            - type: string
            - type: 'null'
          title: Customername
        senderName:
          anyOf:
            - type: string
            - type: 'null'
          title: Sendername
        merchantId:
          $ref: '#/components/schemas/PydanticObjectId'
        merchantName:
          anyOf:
            - type: string
            - type: 'null'
          title: Merchantname
        isPhysical:
          type: boolean
          title: Isphysical
        designTemplate:
          anyOf:
            - type: string
            - type: 'null'
          title: Designtemplate
        customMessage:
          anyOf:
            - type: string
            - type: 'null'
          title: Custommessage
        lastFourDigits:
          type: string
          title: Lastfourdigits
        programId:
          $ref: '#/components/schemas/PydanticObjectId'
        deliverAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Deliverat
        delivered:
          type: boolean
          title: Delivered
          default: false
        card:
          anyOf:
            - $ref: '#/components/schemas/PassCard'
            - type: 'null'
      type: object
      required:
        - id
        - cardNumber
        - balance
        - initialValue
        - status
        - createdAt
        - updatedAt
        - activatedAt
        - expiresAt
        - suspendedReason
        - suspendedUntil
        - suspendedAt
        - customerId
        - customerEmail
        - customerPhone
        - customerName
        - merchantId
        - isPhysical
        - designTemplate
        - customMessage
        - lastFourDigits
        - programId
        - card
      title: GiftCardResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    GiftCardStatus:
      type: string
      enum:
        - pending
        - active
        - suspended
        - expired
        - voided
        - depleted
      title: GiftCardStatus
      description: Gift card status enumeration.
    PassCard:
      properties:
        serialNumber:
          type: string
          title: Serialnumber
        passTypeIdentifier:
          type: string
          title: Passtypeidentifier
        url:
          type: string
          minLength: 1
          format: uri
          title: Url
      type: object
      required:
        - serialNumber
        - passTypeIdentifier
        - url
      title: PassCard
      description: |-
        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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from POST /v2/token.

````