Gift Cards API

This document describes the API endpoints for gift card purchases and balance checking.

Overview

Gift cards allow customers to purchase prepaid value that can be redeemed against bookings. The system supports:

• Fixed value gift cards (e.g., €50 Gift Card)
• Custom range gift cards (customer chooses amount within a range)
• Gift mode with recipient details and personal messages
• Balance tracking and partial redemption

Public Endpoints

These endpoints are available without authentication, requiring only a tenant context.

List Gift Card Products

GET /api/v1/gift-cards/products

Returns available gift card products for the tenant.

Query Parameters:

Parameter	Type	Description
siteId	string	Filter by site (optional)

Response:

{
  "items": [
    {
      "id": "gcp_abc123",
      "name": "€50 Gift Card",
      "description": "Perfect for any occasion",
      "valueType": "fixed",
      "fixedValue": 50,
      "minValue": null,
      "maxValue": null,
      "suggestedValues": null,
      "validityDays": 365,
      "imageUrl": "https://example.com/gift-card.jpg",
      "isActive": true
    },
    {
      "id": "gcp_xyz789",
      "name": "Custom Gift Card",
      "description": "Choose your own amount",
      "valueType": "custom_range",
      "fixedValue": null,
      "minValue": 10,
      "maxValue": 500,
      "suggestedValues": [25, 50, 100, 200],
      "validityDays": 730,
      "imageUrl": null,
      "isActive": true
    }
  ]
}

Get Gift Card Product

GET /api/v1/gift-cards/products/:id

Returns details for a specific gift card product.

Response: Same structure as list item above.

Initiate Purchase

POST /api/v1/gift-cards/purchase

Initiates a gift card purchase. Creates a purchase record in pending status.

Request Body:

{
  "giftCardProductId": "gcp_abc123",
  "amount": 75,
  "purchaserEmail": "buyer@example.com",
  "purchaserName": "John Smith",
  "purchaserPhone": "+358401234567",
  "recipientEmail": "recipient@example.com",
  "recipientName": "Jane Doe",
  "personalMessage": "Happy Birthday!",
  "deliveryDate": "2025-12-25T00:00:00.000Z"
}

Field	Required	Description
giftCardProductId	Yes	ID of the gift card product
amount	For custom_range	Purchase amount (ignored for fixed type)
purchaserEmail	Yes	Email of the person buying
purchaserName	No	Name of the purchaser
purchaserPhone	No	Phone number
recipientEmail	No	Email for gift delivery (defaults to purchaser)
recipientName	No	Recipient's name for gift message
personalMessage	No	Personal message included with gift
deliveryDate	No	Scheduled delivery date (future date)

Response:

{
  "purchaseId": "purchase_abc123",
  "amount": 75,
  "currency": "EUR",
  "status": "pending",
  "paymentOptions": {
    "stripe": true,
    "paytrail": false
  }
}

Create Stripe Payment

POST /api/v1/gift-cards/purchase/:id/payment/stripe

Creates a Stripe PaymentIntent for the purchase.

Response:

{
  "clientSecret": "pi_xxx_secret_yyy",
  "paymentIntentId": "pi_xxx",
  "amount": 7500,
  "currency": "eur"
}

Use the clientSecret with Stripe.js to complete the payment on the frontend.

Get Purchase Status

GET /api/v1/gift-cards/purchase/:id/status

Returns the current status of a purchase.

Response:

{
  "purchaseId": "purchase_abc123",
  "status": "delivered",
  "paymentStatus": "succeeded",
  "voucherCode": "GIFT-ABCD-1234",
  "voucherExpiresAt": "2026-12-16T00:00:00.000Z"
}

Status Values:

Status	Description
pending	Purchase initiated, awaiting payment
payment_failed	Payment attempt failed
paid	Payment succeeded, voucher created
delivered	Gift card email sent
cancelled	Purchase cancelled/refunded

Check Gift Card Balance

GET /api/v1/gift-cards/balance/:code

Public endpoint to check remaining balance on a gift card.

Response:

{
  "code": "GIFT-ABCD-1234",
  "originalValue": 100,
  "currentBalance": 75.5,
  "currency": "EUR",
  "expiresAt": "2026-12-16T00:00:00.000Z",
  "isActive": true,
  "isRedeemed": false
}

Admin Endpoints

These endpoints require admin authentication.

List Gift Card Products (Admin)

GET /api/v1/admin/gift-card-products

Returns all gift card products with pagination.

Query Parameters:

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (default: 20)
isActive	boolean	Filter by active status
siteId	string	Filter by site

Create Gift Card Product

POST /api/v1/admin/gift-card-products

Request Body:

{
  "name": "€100 Gift Card",
  "description": "A great gift for adventure lovers",
  "valueType": "fixed",
  "fixedValue": 100,
  "validityDays": 365,
  "siteId": null,
  "imageUrl": "https://example.com/gift-card-100.jpg",
  "displayOrder": 0,
  "isActive": true
}

For custom range:

{
  "name": "Custom Gift Card",
  "valueType": "custom_range",
  "minValue": 25,
  "maxValue": 500,
  "suggestedValues": [50, 100, 200, 300],
  "validityDays": 730
}

Update Gift Card Product

PATCH /api/v1/admin/gift-card-products/:id

Updates product fields. Partial updates supported.

Deactivate Gift Card Product

DELETE /api/v1/admin/gift-card-products/:id

Soft-deletes (deactivates) a gift card product. Existing vouchers remain valid.

List Purchases (Admin)

GET /api/v1/admin/gift-card-purchases

Query Parameters:

Parameter	Type	Description
page	number	Page number
limit	number	Items per page
status	string	Filter by status
purchaserEmail	string	Filter by purchaser email
dateFrom	string	Start date filter
dateTo	string	End date filter

Resend Delivery Email

POST /api/v1/admin/gift-card-purchases/:id/resend

Resends the gift card delivery email to the recipient.

Payment Flow

Stripe Integration

1. Customer → POST /gift-cards/purchase → Purchase created (pending)
2. Customer → POST /gift-cards/purchase/:id/payment/stripe → Get clientSecret
3. Frontend → Stripe.confirmPayment(clientSecret) → Payment processed
4. Stripe webhook → payment_intent.succeeded → Voucher created
5. System → Email sent to recipient → Status: delivered

Webhook Handling

The system handles Stripe webhooks with metadata:

{
  "type": "gift_card_purchase",
  "purchase_id": "purchase_abc123",
  "tenant_id": "t_demo"
}

On payment_intent.succeeded:

1. Validates purchase exists and is pending
2. Creates voucher with calculated expiry
3. Updates purchase status to paid
4. Sends delivery email to recipient
5. Updates status to delivered

Redemption

Gift cards are redeemed using the standard voucher redemption flow:

POST /api/v1/promotions/vouchers/redeem
{
  "code": "GIFT-ABCD-1234"
}

The voucher balance is decremented by the booking amount. Partial balances can be used across multiple bookings.

Error Codes

Code	Description
GIFT_CARD_PRODUCT_NOT_FOUND	Product doesn't exist or is inactive
GIFT_CARD_INVALID_AMOUNT	Amount outside allowed range
GIFT_CARD_PURCHASE_NOT_FOUND	Purchase ID not found
GIFT_CARD_ALREADY_PAID	Purchase already completed
GIFT_CARD_NOT_FOUND	Gift card code not found

Code Format

Gift card codes follow the format: GIFT-XXXX-XXXX

Characters used: ABCDEFGHJKLMNPQRSTUVWXYZ23456789 (excludes confusing characters like 0/O, 1/I/L)