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

# Redeemgiftcard

> Redeem a specified amount from an active, non-expired gift card and record a REDEMPTION transaction.

Performs an atomic balance deduction (prevents double-spend and race conditions), updates the card status to DEPLETED when balance reaches zero, and inserts a GiftCardTransaction recording the redemption.

Returns:
    RedeemResponse: Contains `transactionId`, `giftCardId`, `amountRedeemed`, `remainingBalance`, `success`, and `message`.

Idempotency Scope:
    Keys are scoped to `programId + redeem + cardId`.
    The same key may be reused for different cards or different gift card actions.



## OpenAPI

````yaml https://api.loyalty.dog/openapi.json post /v2/giftcards/programs/{programId}/cards/{cardId}/redeem
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}/cards/{cardId}/redeem:
    post:
      tags:
        - Gift Cards
      summary: Redeemgiftcard
      description: >-
        Redeem a specified amount from an active, non-expired gift card and
        record a REDEMPTION transaction.


        Performs an atomic balance deduction (prevents double-spend and race
        conditions), updates the card status to DEPLETED when balance reaches
        zero, and inserts a GiftCardTransaction recording the redemption.


        Returns:
            RedeemResponse: Contains `transactionId`, `giftCardId`, `amountRedeemed`, `remainingBalance`, `success`, and `message`.

        Idempotency Scope:
            Keys are scoped to `programId + redeem + cardId`.
            The same key may be reused for different cards or different gift card actions.
      operationId: >-
        redeemGiftCard_v2_giftcards_programs__programId__cards__cardId__redeem_post
      parameters:
        - name: programId
          in: path
          required: true
          schema:
            anyOf:
              - $ref: '#/components/schemas/PydanticObjectId'
              - type: 'null'
            title: Programid
        - name: cardId
          in: path
          required: true
          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/RedeemGiftCardRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemResponse'
        '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
    RedeemGiftCardRequest:
      properties:
        amount:
          anyOf:
            - type: number
              minimum: 0.01
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount
        posTransactionId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Postransactionid
        cashierId:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: Cashierid
        terminalId:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: Terminalid
        description:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Description
      type: object
      required:
        - amount
      title: RedeemGiftCardRequest
    RedeemResponse:
      properties:
        transactionId:
          $ref: '#/components/schemas/PydanticObjectId'
        giftCardId:
          $ref: '#/components/schemas/PydanticObjectId'
        amountRedeemed:
          type: string
          title: Amountredeemed
        remainingBalance:
          type: string
          title: Remainingbalance
        success:
          type: boolean
          title: Success
        message:
          type: string
          title: Message
      type: object
      required:
        - transactionId
        - giftCardId
        - amountRedeemed
        - remainingBalance
        - success
        - message
      title: RedeemResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from POST /v2/token.

````