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

# Customercheckgiftcardbalance

> ### Customer Balance Check (Cross-Program)

Allows customers to check the balance of any gift card without needing to know
the programId. Searches across all programs by card number and security code.

This endpoint is designed for customer-facing applications where the customer
may have cards from multiple merchants/programs.

**Security**:
- Rate limited: 5 requests per minute per IP
- Pattern detection for enumeration attacks
- Card lockout after multiple failed attempts
- Constant-time security code comparison

**Request Body**:
- `cardNumber`: The full 16-digit card number
- `securityCode`: The 6-digit security code

**Returns**:
- Card balance, status, expiration, and activity status

**Status Codes**:
- 200: Balance retrieved successfully
- 404: Card not found or invalid security code
- 429: Rate limited or card locked



## OpenAPI

````yaml https://api.loyalty.dog/openapi.json post /v2/giftcards/customer/balance-check
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/customer/balance-check:
    post:
      tags:
        - Gift Cards
      summary: Customercheckgiftcardbalance
      description: >-
        ### Customer Balance Check (Cross-Program)


        Allows customers to check the balance of any gift card without needing
        to know

        the programId. Searches across all programs by card number and security
        code.


        This endpoint is designed for customer-facing applications where the
        customer

        may have cards from multiple merchants/programs.


        **Security**:

        - Rate limited: 5 requests per minute per IP

        - Pattern detection for enumeration attacks

        - Card lockout after multiple failed attempts

        - Constant-time security code comparison


        **Request Body**:

        - `cardNumber`: The full 16-digit card number

        - `securityCode`: The 6-digit security code


        **Returns**:

        - Card balance, status, expiration, and activity status


        **Status Codes**:

        - 200: Balance retrieved successfully

        - 404: Card not found or invalid security code

        - 429: Rate limited or card locked
      operationId: customerCheckGiftCardBalance_v2_giftcards_customer_balance_check_post
      parameters:
        - name: programId
          in: query
          required: false
          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: 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/BalanceCheckRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceCheckResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
components:
  schemas:
    PydanticObjectId:
      type: string
      maxLength: 24
      minLength: 24
      pattern: ^[0-9a-f]{24}$
      example: 5eb7cf5a86d9755df3a6c593
    BalanceCheckRequest:
      properties:
        cardNumber:
          type: string
          maxLength: 20
          title: Cardnumber
        securityCode:
          type: string
          maxLength: 6
          title: Securitycode
        captchaToken:
          anyOf:
            - type: string
              maxLength: 4096
            - type: 'null'
          title: Captchatoken
      type: object
      required:
        - cardNumber
        - securityCode
      title: BalanceCheckRequest
    BalanceCheckResponse:
      properties:
        id:
          $ref: '#/components/schemas/PydanticObjectId'
        programId:
          $ref: '#/components/schemas/PydanticObjectId'
        cardNumber:
          type: string
          title: Cardnumber
        lastFourDigits:
          type: string
          title: Lastfourdigits
        balance:
          type: string
          title: Balance
        status:
          $ref: '#/components/schemas/GiftCardStatus'
        expiresAt:
          type: string
          format: date-time
          title: Expiresat
        isActive:
          type: boolean
          title: Isactive
      type: object
      required:
        - id
        - programId
        - cardNumber
        - lastFourDigits
        - balance
        - status
        - expiresAt
        - isActive
      title: BalanceCheckResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GiftCardStatus:
      type: string
      enum:
        - pending
        - active
        - suspended
        - expired
        - voided
        - depleted
      title: GiftCardStatus
      description: Gift card status enumeration.
    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.

````