---
title: "Reloadgiftcard"
method: POST
path: "/v2/giftcards/programs/{programId}/cards/{cardId}/reload"
tags: ["Gift Cards"]
---

# Reloadgiftcard

`POST /v2/giftcards/programs/{programId}/cards/{cardId}/reload`

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

## Path parameters

- `programId` string, required
- `cardId` string, required

## Headers

- `idempotency-key` string, nullable
- `X-Eposn-Customer-Token` string, nullable
- `X-Eposn-Merchant-Token` string, nullable

## Request body

- ReloadGiftCardRequest
  - `amount` union, required
    - number
    - string
  - `referenceId` string, nullable
  - `description` string, nullable

## Response `200`

Successful Response

- GiftCardResponse
  - `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

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