Reloadgiftcard

curl --request POST \
  --url https://api.loyalty.dog/v2/giftcards/programs/{programId}/cards/{cardId}/reload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 2500.005,
  "referenceId": "<string>",
  "description": "<string>"
}
'

{
  "id": "5eb7cf5a86d9755df3a6c593",
  "cardNumber": "<string>",
  "balance": "<string>",
  "initialValue": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "activatedAt": "2023-11-07T05:31:56Z",
  "expiresAt": "2023-11-07T05:31:56Z",
  "suspendedReason": "<string>",
  "suspendedUntil": "2023-11-07T05:31:56Z",
  "suspendedAt": "2023-11-07T05:31:56Z",
  "customerId": "5eb7cf5a86d9755df3a6c593",
  "customerEmail": "<string>",
  "customerPhone": "<string>",
  "customerName": "<string>",
  "merchantId": "5eb7cf5a86d9755df3a6c593",
  "isPhysical": true,
  "designTemplate": "<string>",
  "customMessage": "<string>",
  "lastFourDigits": "<string>",
  "programId": "5eb7cf5a86d9755df3a6c593",
  "card": {
    "serialNumber": "<string>",
    "passTypeIdentifier": "<string>",
    "url": "<string>"
  },
  "senderName": "<string>",
  "merchantName": "<string>",
  "deliverAt": "2023-11-07T05:31:56Z",
  "delivered": false
}

Gift Cards

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

{
    "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

POST

giftcards

programs

{programId}

cards

{cardId}

reload

Reloadgiftcard

curl --request POST \
  --url https://api.loyalty.dog/v2/giftcards/programs/{programId}/cards/{cardId}/reload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 2500.005,
  "referenceId": "<string>",
  "description": "<string>"
}
'

{
  "id": "5eb7cf5a86d9755df3a6c593",
  "cardNumber": "<string>",
  "balance": "<string>",
  "initialValue": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "activatedAt": "2023-11-07T05:31:56Z",
  "expiresAt": "2023-11-07T05:31:56Z",
  "suspendedReason": "<string>",
  "suspendedUntil": "2023-11-07T05:31:56Z",
  "suspendedAt": "2023-11-07T05:31:56Z",
  "customerId": "5eb7cf5a86d9755df3a6c593",
  "customerEmail": "<string>",
  "customerPhone": "<string>",
  "customerName": "<string>",
  "merchantId": "5eb7cf5a86d9755df3a6c593",
  "isPhysical": true,
  "designTemplate": "<string>",
  "customMessage": "<string>",
  "lastFourDigits": "<string>",
  "programId": "5eb7cf5a86d9755df3a6c593",
  "card": {
    "serialNumber": "<string>",
    "passTypeIdentifier": "<string>",
    "url": "<string>"
  },
  "senderName": "<string>",
  "merchantName": "<string>",
  "deliverAt": "2023-11-07T05:31:56Z",
  "delivered": false
}

Authorizations

Authorization

string

header

required

JWT access token obtained from POST /v2/token.

Headers

idempotency-key

string | null

X-Eposn-Customer-Token

string | null

X-Eposn-Merchant-Token

string | null

Path Parameters

programId

string | null

required

Required string length: 24

Pattern: ^[0-9a-f]{24}$

Example:

"5eb7cf5a86d9755df3a6c593"

cardId

string | null

required

Required string length: 24

Pattern: ^[0-9a-f]{24}$

Example:

"5eb7cf5a86d9755df3a6c593"

Body

application/json

amount

required

Required range: 0.01 <= x <= 5000

referenceId

string | null

Maximum string length: 100

description

string | null

Maximum string length: 500

Response

Successful Response

string

required

Required string length: 24

Pattern: ^[0-9a-f]{24}$

Example:

"5eb7cf5a86d9755df3a6c593"

cardNumber

string

required

balance

string

required

initialValue

string

required

status

enum<string>

required

Gift card status enumeration.

Available options:

pending,

active,

suspended,

expired,

voided,

depleted

createdAt

string<date-time>

required

updatedAt

string<date-time> | null

required

activatedAt

string<date-time> | null

required

expiresAt

string<date-time>

required

suspendedReason

string | null

required

suspendedUntil

string<date-time> | null

required

suspendedAt

string<date-time> | null

required

customerId

string | null

required

Required string length: 24

Pattern: ^[0-9a-f]{24}$

Example:

"5eb7cf5a86d9755df3a6c593"

customerEmail

string | null

required

customerPhone

string | null

required

customerName

string | null

required

merchantId

string

required

Required string length: 24

Pattern: ^[0-9a-f]{24}$

Example:

"5eb7cf5a86d9755df3a6c593"

isPhysical

boolean

required

designTemplate

string | null

required

customMessage

string | null

required

lastFourDigits

string

required

programId

string

required

Required string length: 24

Pattern: ^[0-9a-f]{24}$

Example:

"5eb7cf5a86d9755df3a6c593"

card

PassCard · object

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

Show child attributes

senderName

string | null

merchantName

string | null

deliverAt

string<date-time> | null

delivered

boolean

default:false

Activategiftcard Reloadgiftcardbynumber