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

# Reloadgiftcard

> ### Reload Gift Card

Adds funds to an active gift card. Creates a RELOAD transaction for audit trail.

**Business Rules**:
- Only ACTIVE cards can be reloaded
- Card must not be expired
- Reload amount: $0.01 - $5,000 per transaction
- Maximum card balance: $10,000
- New balance = current balance + reload amount
- Transaction includes before/after balance tracking

**Path Parameters**:
- `programId`: MongoDB ObjectId of the loyalty program
- `cardId`: MongoDB ObjectId of the gift card

**Request Body**:
- `amount`: Amount to add ($0.01 - $5,000)
- `referenceId`: External reference ID for tracking (optional)
- `description`: Transaction description (optional, defaults to "Gift card reload")

**Returns**:
- Updated gift card details with new balance
- Balance reflects immediately after reload

**Status Codes**:
- 200: Gift card reloaded successfully
- 400: Cannot reload (inactive, expired, or would exceed max balance of $10,000)
- 404: Gift card not found or doesn't belong to program
- 401: Unauthorized

**Error Response (Max Balance Exceeded)**:
```json
{
    "detail": "Reload would exceed maximum card balance",
    "currentBalance": 9500.00,
    "reloadAmount": 1000.00,
    "maxBalance": 10000.00,
    "availableReloadAmount": 500.00
}
```

**Idempotency Scope**:
- Idempotency keys are scoped to `programId + reload + 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}/reload
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}/reload:
    post:
      tags:
        - Gift Cards
      summary: Reloadgiftcard
      description: >-
        ### Reload Gift Card


        Adds funds to an active gift card. Creates a RELOAD transaction for
        audit trail.


        **Business Rules**:

        - Only ACTIVE cards can be reloaded

        - Card must not be expired

        - Reload amount: $0.01 - $5,000 per transaction

        - Maximum card balance: $10,000

        - New balance = current balance + reload amount

        - Transaction includes before/after balance tracking


        **Path Parameters**:

        - `programId`: MongoDB ObjectId of the loyalty program

        - `cardId`: MongoDB ObjectId of the gift card


        **Request Body**:

        - `amount`: Amount to add ($0.01 - $5,000)

        - `referenceId`: External reference ID for tracking (optional)

        - `description`: Transaction description (optional, defaults to "Gift
        card reload")


        **Returns**:

        - Updated gift card details with new balance

        - Balance reflects immediately after reload


        **Status Codes**:

        - 200: Gift card reloaded successfully

        - 400: Cannot reload (inactive, expired, or would exceed max balance of
        $10,000)

        - 404: Gift card not found or doesn't belong to program

        - 401: Unauthorized


        **Error Response (Max Balance Exceeded)**:

        ```json

        {
            "detail": "Reload would exceed maximum card balance",
            "currentBalance": 9500.00,
            "reloadAmount": 1000.00,
            "maxBalance": 10000.00,
            "availableReloadAmount": 500.00
        }

        ```


        **Idempotency Scope**:

        - Idempotency keys are scoped to `programId + reload + cardId`

        - The same key may be reused for different cards or different gift card
        actions
      operationId: >-
        reloadGiftCard_v2_giftcards_programs__programId__cards__cardId__reload_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/ReloadGiftCardRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GiftCardResponse'
        '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
    ReloadGiftCardRequest:
      properties:
        amount:
          anyOf:
            - type: number
              maximum: 5000
              minimum: 0.01
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount
        referenceId:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Referenceid
        description:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Description
      type: object
      required:
        - amount
      title: ReloadGiftCardRequest
    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
    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.
    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
    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.

````