Developers

Entities and Admin API

The gift card data are regular Shopware entities, so you can read and write them through the Admin API, e.g. from a POS or ERP.

Entity	Contents
lae_giftcard	Gift cards: code, balance, initialAmount, currencyId, languageId, salesChannelId, originOrderId, originProductId, validUntil, payload (personalisation)
lae_giftcard_transaction	Changes of the balance of a gift card: giftcardId, amount (positive redeems, negative tops up), orderId, comment
lae_product_giftcard	The gift card settings of a product (association laeGiftcardConfig on product)
lae_giftcard_design	Gift card designs and their layers

Book a transaction to change the balance of a gift card. The amount of a transaction is subtracted from the balance: a positive amount redeems, a negative amount tops up. For example, when a gift card is used in a physical store:

POST /api/lae-giftcard-transaction
Content-Type: application/json

{
  "giftcardId": "<gift card id>",
  "amount": 25,
  "comment": "Redeemed in the Antwerp store"
}

When a transaction is written or deleted, the balance of the gift card is recalculated: the initial amount minus the sum of all transactions. If balances are ever out of sync, recalculate them with:

bin/console kw:giftcard:calculate-balance

Actions

Route	Does
POST /api/_action/lae-giftcard/create	Creates a gift card (name, description, balance, originProductId, currencyId, languageId, salesChannelId)
POST /api/_action/lae-giftcard/resend/{giftcardId}	Sends the gift card e-mail again
GET /api/_action/lae-giftcard/download/{giftcardId}	Returns the PDF of the gift card
GET /api/_action/lae-giftcard/overview	The numbers of the overview in Orders > Gift cards

Store API and headless

Buying a gift card: add the product to the cart as usual, and send the amount and the personalisation per product ID in lineItems in the same request:

POST /store-api/checkout/cart/line-item
Content-Type: application/json

{
  "items": [
    { "type": "product", "referencedId": "<product id>", "quantity": 1 }
  ],
  "lineItems": {
    "<product id>": {
      "giftcardAmount": 50,
      "giftcardRecipientName": "Alex",
      "giftcardSenderName": "Sam",
      "giftcardRecipientEmail": "[email protected]",
      "giftcardDeliveryDate": "2026-12-24",
      "giftcardMessage": "Happy birthday!"
    }
  }
}

Redeeming a gift card: add the code like a promotion code:

POST /store-api/checkout/cart/line-item
Content-Type: application/json

{
  "items": [
    { "type": "promotion", "referencedId": "ABCD1234EFGH5678" }
  ]
}

The applied gift cards are in the lae-giftcards extension of the cart.

Removing a gift card from the cart:

DELETE /store-api/checkout/cart/giftcard
Content-Type: application/json

{
  "codes": ["ABCD1234EFGH5678"]
}

Events

Event	When
Laenen\Giftcard\Event\GiftcardCreatedEvent	A gift card was created for an order
Laenen\Giftcard\Event\GiftcardRenderDataEvent	Before a gift card PDF is rendered, see PDF data
Laenen\Giftcard\Event\GiftcardTemplateConfigEvent	Before a gift card PDF is rendered, to change the templateConfig array
Laenen\Giftcard\Core\Checkout\Event\GiftcardCartConvertedEvent	A redeemed gift card is stored on the order. Change the stored data with setConverted()
Laenen\Giftcard\Core\Checkout\Event\BeforeGiftcardRemovedEvent	A gift card is about to be removed from the cart
Laenen\Giftcard\Core\Checkout\Event\AfterGiftcardRemovedEvent	Gift cards were removed from the cart

PDF data

Subscribe to GiftcardRenderDataEvent to add data to the Twig context of the PDF. Add it as an extension of the gift card:

public function onGiftcardRenderData(GiftcardRenderDataEvent $event): void
{
    $event->getGiftcardEntity()->addExtension('myData', new ArrayStruct(['foo' => 'bar']));
}

Use it in a design with {{ giftcard.extensions.myData.foo }}. The plugin itself adds the order the gift card was bought in as giftcard.extensions.originOrder.

Gift card codes

Codes are generated by Laenen\Giftcard\Service\GiftcardCodeService, which implements Laenen\Giftcard\Service\GiftcardCodeServiceInterface. Override this service to generate your own codes, e.g. with a prefix. The code length is set in the plugin configuration.

Line items

• Bought gift cards are product line items with the payload giftcardAmount. The personalisation is in the payload giftcardPersonalisation.
• Redeemed gift cards carry the product number of the gift card product in the payload of their line item, for ERPs such as Xentral.
• The order stores the redeemed gift cards in the custom field lae-giftcards.

E-invoices

XRechnung and ZUGFeRD invoices show gift cards that pay the order as a prepaid amount, gift cards that lower the VAT (single-purpose vouchers) as an allowance, and bought gift cards with a 0 % VAT breakdown, so the totals add up, also for orders without VAT (reverse charge).