Skip to main content

Gift Cards

Creating and managing gift cards via the API.

Overview​

The Molzait API allows you to:

  • Create gift cards with initial balance
  • Top up existing gift cards
  • Redeem gift cards for reservations
  • Check gift card balance

Create Gift Card​

Request​

POST /external/gift-cards

Parameters​

  • amount (required): Initial balance in cents (e.g., 10000 for €100)
  • templateId (required): Gift card template ID
  • expiresOnDay (required): Expiration date (YYYY-MM-DD)
  • email (optional): Customer email address
  • locale (optional): Customer locale (en or de)
  • id (optional): Custom gift card code
  • paymentReference (optional): Payment reference

Example​

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "templateId": "template-123",
    "expiresOnDay": "2050-12-31",
    "email": "recipient@example.com",
    "locale": "en"
  }' \
  https://api.molzait.com/external/gift-cards

Response​

{
  "id": "ABC123XYZ",
  "amount": 10000,
  "remainingAmount": 10000,
  "templateId": "template-123",
  "image": {
    "path": "gift-cards/template.jpg",
    "url": "https://storage.googleapis.com/..."
  },
  "email": "recipient@example.com",
  "expiresOnDay": "2050-12-31",
  "locale": "en",
  "creationTimestamp": "2025-12-03T10:30:00Z"
}

Gift Card Templates​

Templates define the types and configurations of gift cards available at your restaurant. Each template specifies:

  • Visual design (image, colors)
  • Value amounts or experience types
  • Expiration period
  • Description in multiple languages

Template Types​

Currently, only value templates are supported:

  • Value Templates (type: "value"): Gift cards with a monetary value that can be used for any reservation or purchase. These are flexible and can be applied to any experience at the restaurant.

Future support may include experience-specific templates (e.g., "Chef's Tasting Menu", "Wine Pairing Dinner") that are tied to specific dining experiences.

List Available Templates​

Get all gift card templates configured for your restaurant:

Request​

GET /external/gift-cards/templates

Example​

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.molzait.com/external/gift-cards/templates

Response​

[
  {
    "id": "template-123",
    "type": "value",
    "archived": false,
    "expiresAfterDays": 365,
    "experienceDescription": {
      "de": "Gutschein für Restaurant",
      "en": "Restaurant Gift Card"
    },
    "variations": [
      { "amount": 5000 },
      { "amount": 10000 }
    ]
  }
]

Template Fields​

  • id: Unique template identifier (required when creating gift cards)
  • type: Template type ("value" only for now)
  • archived: Whether template is still active
  • expiresAfterDays: Days until gift card expires after creation
  • experienceDescription: Multi-language description
  • variations: Suggested amounts for frontend display (in cents) - API can accept any amount

Note: The variations field is purely for frontend convenience (e.g., showing preset buttons). When creating gift cards via the API, you can specify any amount regardless of the variations listed.

Create Gift Card Transaction​

Top up or redeem a gift card using transactions:

Request​

POST /external/gift-cards/{giftCardId}/transactions

Example - Top Up​

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "successful",
    "amount": 5000,
    "reference": "payment-ref-123"
  }' \
  https://api.molzait.com/external/gift-cards/ABC123XYZ/transactions

Example - Redeem​

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "successful",
    "amount": -2000,
    "reference": "reservation-456"
  }' \
  https://api.molzait.com/external/gift-cards/ABC123XYZ/transactions

Check Gift Card Balance​

Request​

GET /external/gift-cards/{giftCardId}

Example​

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.molzait.com/external/gift-cards/gc_abc123

Response​

{
  "id": "ABC123XYZ",
  "amount": 10000,
  "remainingAmount": 10000,
  "templateId": "template-123",
  "expiresOnDay": "2050-12-31"
}

Update Gift Card Transaction​

Update transaction status (e.g., from pending to successful):

Request​

PATCH /external/gift-cards/{giftCardId}/transactions/{transactionId}

Example​

curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "successful",
    "reference": "updated-ref"
  }' \
  https://api.molzait.com/external/gift-cards/ABC123XYZ/transactions/txn-123

Refund Gift Card Transaction​

Refund a transaction to restore the gift card balance:

Request​

POST /external/gift-cards/{giftCardId}/transactions/{transactionId}/refund

Example​

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.molzait.com/external/gift-cards/ABC123XYZ/transactions/txn-123/refund

Transaction Status​

  • pending: Transaction initiated but not yet processed
  • successful: Transaction completed successfully

Error Handling​

400 Bad Request - Insufficient Balance​

{
  "statusCode": 400,
  "message": "Gift card balance insufficient",
  "error": "Bad Request"
}

404 Not Found - Invalid Gift Card​

{
  "statusCode": 404,
  "message": "Gift card not found",
  "error": "Not Found"
}

410 Gone - Expired Gift Card​

{
  "statusCode": 410,
  "message": "Gift card has expired",
  "error": "Gone"
}

Best Practices​

  1. Validate amount - Ensure positive values in cents
  2. Check balance - Verify sufficient balance before redemption
  3. Handle expiration - Warn users of upcoming expiration
  4. Secure codes - Treat gift card codes like passwords
  5. Email validation - Verify recipient email is valid

Next Steps​