Sign in

v2

latestOpenAPI 3.1.02026-08-01244220427.0 KB
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/v2/giftcards/programs/{programId}/cards/{cardId}/activate

Path parameters

programIdstring required
Example:5eb7cf5a86d9755df3a6c593
cardIdstring required
Example:5eb7cf5a86d9755df3a6c593

Headers

idempotency-keystring nullable
X-Eposn-Customer-Tokenstring nullable
X-Eposn-Merchant-Tokenstring nullable

Request body

customerEmailstring email nullable
customerPhonestring nullable
customerNamestring nullable
securityCodestring nullable

Security code required for customer self-activation

Response

Successful Response

idstring required
cardNumberstring required
balancestring required
initialValuestring required
status'pending' | 'active' | 'suspended' | 'expired' | 'voided' | 'depleted' required

Gift card status enumeration.

createdAtstring date-time required
updatedAtstring date-time nullable required
activatedAtstring date-time nullable required
expiresAtstring date-time required
suspendedReasonstring nullable required
suspendedUntilstring date-time nullable required
suspendedAtstring date-time nullable required
customerIdstring required
customerEmailstring nullable required
customerPhonestring nullable required
customerNamestring nullable required
senderNamestring nullable
merchantIdstring required
merchantNamestring nullable
isPhysicalboolean required
designTemplatestring nullable required
customMessagestring nullable required
lastFourDigitsstring required
programIdstring required
deliverAtstring date-time nullable
deliveredboolean

Example response

{
  "id": "5eb7cf5a86d9755df3a6c593",
  "customerId": "5eb7cf5a86d9755df3a6c593",
  "merchantId": "5eb7cf5a86d9755df3a6c593",
  "programId": "5eb7cf5a86d9755df3a6c593"
}