Activategiftcard

curl --request POST \
  --url https://api.loyalty.dog/v2/giftcards/programs/{programId}/cards/{cardId}/activate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerEmail": "[email protected]",
  "customerPhone": "<string>",
  "customerName": "<string>",
  "securityCode": "<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

Activategiftcard

Activate Gift Card

Activates a pending gift card and loads the initial balance. Creates an ACTIVATION transaction for audit trail.

Business Rules:

Only PENDING cards can be activated
Card must not be expired
Balance is set to initialValue upon activation
Status changes from PENDING to ACTIVE
Customer information can be updated during activation
Activation creates a transaction record
Authenticated customer session is required

Path Parameters:

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

Request Body:

customerEmail: Customer email (optional, updates card if provided)
customerName: Customer name (optional, updates card if provided)

Returns:

Activated gift card details with updated balance and ACTIVE status
Includes activatedAt timestamp

Status Codes:

200: Gift card activated successfully
400: Card cannot be activated (already active, expired, or invalid status)
404: Gift card not found or doesn’t belong to program
409: Activation conflicted with concurrent update
401: Unauthorized

Idempotency Scope:

Idempotency keys are scoped to programId + activate + cardId
The same key may be reused for different cards or different gift card actions

POST

giftcards

programs

{programId}

cards

{cardId}

activate

Activategiftcard

curl --request POST \
  --url https://api.loyalty.dog/v2/giftcards/programs/{programId}/cards/{cardId}/activate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerEmail": "[email protected]",
  "customerPhone": "<string>",
  "customerName": "<string>",
  "securityCode": "<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

customerEmail

string<email> | null

customerPhone

string | null

Maximum string length: 50

customerName

string | null

Maximum string length: 255

securityCode

string | null

Security code required for customer self-activation

Maximum string length: 6

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

Resendgiftcardsecuritycode Reloadgiftcard