Gift Cards

The gift card plugin adds a gift_cards entity type, balance ledger, and a checkout hook that applies card balances as a payment method.

Install

bun add @porulle/plugin-giftcards

Register

commerce.config.ts

import { giftCardPlugin } from "@porulle/plugin-giftcards";

export default defineConfig({
  plugins: [giftCardPlugin()],
});

Update drizzle.config.ts to include the plugin schema:

drizzle.config.ts

import { getSchemaFiles } from "@porulle/core";
import { createRequire } from "node:module";

const resolve = createRequire(import.meta.url).resolve;

schema: [
  ...getSchemaFiles(),
  resolve("@porulle/plugin-giftcards/schema"),
],

Push the new tables and restart:

bunx drizzle-kit push --config drizzle.config.ts
bun run src/server.ts

Issue a gift card

curl -X POST http://localhost:4000/api/gift-cards \
  -H "content-type: application/json" \
  -H "x-api-key: $PORULLE_API_KEY" \
  -d '{"amount": 5000, "currency": "USD", "recipientEmail": "friend@example.com"}'

The response includes a code field. Share the code with the recipient.

Redeem at checkout

Pass the gift card code in the checkout request:

curl -X POST http://localhost:4000/api/checkout \
  -H "content-type: application/json" \
  -H "x-api-key: $PORULLE_API_KEY" \
  -d '{
    "cartId": "...",
    "giftCardCode": "GC-XXXX-YYYY",
    "paymentMethodId": "stripe",
    "currency": "USD",
    "shippingAddress": { ... }
  }'

The plugin applies the gift card balance first and charges the remainder to the payment method. If the gift card covers the full order, no payment method is required.

Check a balance

curl "http://localhost:4000/api/gift-cards/GC-XXXX-YYYY/balance" \
  -H "x-api-key: $PORULLE_API_KEY"

Related

• Plugin API Reference — gift card plugin manifest and endpoints
• Build a Loyalty Plugin — learn how plugins define schema and hooks
• Hook System guide — how the redemption hook integrates with checkout