Getgiftcarddetails

Get Gift Card Details

Retrieves comprehensive details for a specific gift card including current balance, status, and optionally the complete transaction history.

Card Information:

• Current balance and initial value
• Card status (pending, active, expired, voided, depleted)
• Card number (16 digits) and last four digits
• Customer information (email, name, ID)
• Merchant identifier
• Expiration and activation dates
• Physical/digital card indicator
• Design template and custom message

Business Rules:

• Card number is returned in full (security code is never exposed)
• Status reflects current card state
• Timestamps in UTC
• Optional transaction history sorted newest first

Path Parameters:

• programId: MongoDB ObjectId of the loyalty program
• cardId: MongoDB ObjectId of the gift card

Query Parameters:

• include_transactions: Include full transaction history (default: false)
  • Use ?include_transactions=true to include all transactions
  • Transactions sorted by createdAt descending (newest first)

Returns:

• Gift card details object
• Optional: transactions array if include_transactions=true

Response Example (without transactions):

{
    "id": "507f191e810c19729de860ea",
    "cardNumber": "4000123456789012",
    "lastFourDigits": "9012",
    "balance": 100.00,
    "initialValue": 100.00,
    "status": "active",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-15T10:30:00Z",
    "activatedAt": "2025-01-02T14:20:00Z",
    "expiresAt": "2026-01-01T00:00:00Z",
    "customerId": "customer_456",
    "customerEmail": "[email protected]",
    "customerName": "John Doe",
    "merchantId": "merchant_123",
    "isPhysical": false,
    "designTemplate": "birthday",
    "customMessage": "Happy Birthday!"
}

Response Example (with transactions):

{
    "id": "507f191e810c19729de860ea",
    ...card details...,
    "transactions": [
        {
            "id": "507f1f77bcf86cd799439011",
            "transactionType": "REDEMPTION",
            "amount": -25.50,
            "balanceBefore": 100.00,
            "balanceAfter": 74.50,
            ...transaction details...
        }
    ]
}

Status Codes:

• 200: Gift card details retrieved successfully
• 404: Gift card not found or doesn’t belong to program
• 401: Unauthorized