Skip to content

Gift Cards ​

Gift cards sold online and at the front desk: the amounts you offer, a message and the day it arrives, an email with a card to print, the balance spent at the till over one visit or several, refunds back onto the card and a ledger of every change; no expiry date, as Canadian provinces require.

kitloom/gift-cards · admins: kitloom/gift-cards-filament, kitloom/gift-cards-nova

Video lessons ​

Recorded in the Filament admin; the Nova admin works the same way.

Gift cards your clients buy for themselves or for someone else. A card is a code with a balance: the money is yours, held for whoever has the code. It is spent over one visit or several, and what is left stays on the card for next time. Every change of a balance — the card made, a payment, a refund back onto it, a correction — is a line of the card's ledger, and nothing is ever deleted.

The admin is kitloom/gift-cards-filament or kitloom/gift-cards-nova.

Setting it up ​

Gift card settings

Gift Cards → Settings:

  1. Sell gift cards online — on by default: the site sells cards through its online payment methods. Off, they are sold at the front desk only.
  2. Amounts offered — what a buyer picks from on the site (25, 50, 100, 150 by default), and the smallest and the largest amount of their own a buyer may type (25 and 500). Both 0: only the amounts offered.
  3. Currency — empty takes the bookings' currency, or the shop's.
  4. Months a card is good for — 0 by default: a card never expires. Manitoba and most Canadian provinces do not allow an expiry date on a gift card; set it only where the law of your place does.
  5. A word in the card's email — a line of your own under the card: how to book, where to park.
  6. Balance check on the site — on by default: anyone with a code sees what is left on it at /gift-card/.

Selling ​

Sell a gift card at the front desk

Online (with kitloom/payments and a theme that draws the giftCards part — Atelier's Gift cards page). The buyer picks one of the amounts or types one in your range, says whom it is for, a message and the day it goes, and pays through your online payment methods that take the cards' currency. The card is made when the payment is confirmed, never before, and once however many times the gateway says so. The buyer comes back to a page that says where it went, and gets their receipt and a copy.

At the front desk. Gift Cards → Sell a gift card in the admin: the amount, how it was paid (cash, your bank terminal, another way) and whom it is for. The code shows once, and Print gives the card to hand over. A manager may also give a card away, given, not paid; the ledger says so.

A card ​

Pay with a gift card at the till

A card's code has sixteen characters in four groups, 7K2Q-M4XD-9PRT-HC3B. There is no I, L, O or U, so nothing reads as something else, and the last character checks the others: a code mistyped at the till is turned away at once. It may be typed in any case, with or without the dashes.

The code is the holder's. kitloom keeps it encrypted and shows only its last four characters — •••• HC3B — in the admin, the lists and the exports, so a copy of your database spends nobody's card.

Sent by email. A card for someone else goes to them, with the buyer's message, on the day the buyer chose — at nine that morning, your time — or at once. The buyer gets a copy at once, saying when it goes. Both carry the card to print, a PDF with your name, the amount, the code and the message. A card without an email is printed and handed over: nothing is sent.

What is left on it is at /gift-card/ for whoever has the code: the balance, where the card stands, its last uses. One place may try five codes a minute, and one code is tried five times a minute from anywhere, so codes cannot be guessed there.

At the till (kitloom/booking-checkouts). Take a payment — in either admin or the staff's app — offers Gift card: the code typed, Check says what is left on it, and it pays what is due or all it holds; the rest is paid another way. The bill and the receipt name it by its last four characters. Give money back → Back onto the gift card puts what it paid back on it, never as cash.

Taxes. A gift card is not taxed when it is sold: it is money held for the holder. The GST and other taxes come with the services it pays for, on the bill, as they always do. Ask your accountant how your books should show what the cards still hold.

Who may do what ​

What the cards hold, and putting one right
  • Sell gift cards at the front desk and send them again (sell_gift_cards) — whoever manages the bookings has it when the module first appears.
  • Correct and cancel gift cards, and set them up (manage_gift_cards) — a correction or a cancellation says why, in the card's ledger.

Spending a card at the till asks only what taking a payment there asks.

For the developer ​

WhatWhere
Cardstable gift_cards, model Kitloom\GiftCards\Models\GiftCard (GiftCard::KEY)
The ledgertable gift_card_entries, model Models\GiftCardEntry
The only writerGiftCardWriter: issue(), spend(), giveBack(), adjust(), cancel()
ReadingGiftCards: find($typed), outstanding()
CodesCodes: make(), normalize($typed), hash($code)
Email and the card to printDelivery\Delivery, Delivery\GiftCardEmail, Delivery\CardPdf (view kitloom-gift-cards::pdf.card)
SettingsGiftCardsOptions, read through GiftCardSettings
EventsEvents\GiftCardIssued, Events\GiftCardSpent
Selling onlineSelling\Purchases (start(), paid()), Selling\GiftCardPurchase (a Payable), REST gift-cards/v1/purchases, the giftCards page part (Site\GiftCardsData), /gift-card/thanks/{token} — only with kitloom/payments
Printing/gift-cards/print/{card}, for whoever sells cards
Schedulergift-cards:send every five minutes: the cards whose day has come
The tillTill\GiftCardTender, booking-checkouts' BillTender (gift_card), tagged when the till is installed
php
use Kitloom\GiftCards\GiftCards;
use Kitloom\GiftCards\GiftCardWriter;

$card = app(GiftCardWriter::class)->issue([
    'amount' => '50',
    'paid_by' => 'cash',               // cash, own_terminal, other, given (a manager's gift)
    'recipient_name' => 'Ada',
    'recipient_email' => '[email protected]',
    'buyer_name' => 'Ben',
    'message' => 'Happy birthday!',
    'send_on' => '2026-12-25',         // at nine that morning, the site's time; none — at once
], $user);

$card = app(GiftCards::class)->find('7k2q m4xd 9prt hc3b');
$entry = app(GiftCardWriter::class)->spend($card, 2500, 'bill-payment:41', $user);   // takes at most what is left

spend() takes a reference — what the money paid for — and a payment told twice by the same reference is spent once. giveBack() puts back onto the card no more than it paid for that reference. Each takes the card's row under a lock, so two tills never spend the same dollar.

The card's look. Put your own resources/views/vendor/kitloom-gift-cards/pdf/card.blade.php in the application or the theme. dompdf draws it: plain HTML with the CSS inline, and nothing fetched from elsewhere.

Configuration — config/kitloom-gift-cards.php (php artisan vendor:publish --tag=kitloom-gift-cards-config): the admin sections (filament.register, nova.register), the balance page's route (routes.register), and what other modules read (notifications, webhooks, ai, api, sheets, privacy).

The models come from the ModelRegistry: ModelRegistry::use(GiftCard::KEY, App\Models\GiftCard::class) in a provider of the application puts its own in their place.

Tests ​

From the application that installs the package: php vendor/bin/phpunit --testsuite GiftCards.

Read more ​

kitloom — sites on Laravel, built for you and run with AI.
Contact · Services · License · Refunds · Privacy · Community · YouTube · [email protected]