Exploring Commerce Layer gift cards.

How gift cards work in Commerce Layer

Commerce Layer offers a fully-fledged gift card service that’s deeply integrated with its core order and inventory infrastructure, while remaining flexible enough to support external integrations. Whether you’re launching a new program or connecting an existing gift card system, Commerce Layer allows you to issue, redeem, and manage gift cards across any touchpoint — without compromising on scalability or control.

Core concepts and features

Gift cards are a unique type of payment method: customers can purchase gift cards and use them to pay for an order. But gift cards are way more than this.

A gift card represents a “credit” a customer owns: this means that gift cards can also be used by customer service teams to refund or gift customers in a simple yet effective way.

There are two types of gift cards:

• Rechargeable (digital wallet) — card balance can be used and reloaded at any time.
• Non-rechargeable (standard) – — card balance cannot be reloaded.

Both types can be further split into:

• Single-use — card can only be used once disregarding the balance.
• Multiple-use — card can be reused until balance is positive.

Gift cards can be assigned either to a market or to a currency (in the latter case, it’s essential that the gift card currency aligns with the currency of the active market selected by the customer).

The brand new Gift cards app

The Gift cards app in the Dashboard is the easiest way to visually create and manage gift cards.

Located under the Marketing section in the left sidebar of the Dashboard the Gift cards app opens showing all the currently existing gift cards:

From the app you can create a new gift card and namely:

• Create a code (this will be the unique identifier of the gift card, if not provided it will be automatically generated).
• Assign the gift card to a market or a currency.
• Set the initial balance and the max balance (useful in case of rechargeable gift cards).
• Add an expiration date.
• Set the recipient email (we’ll dig further on this later).
• Add an image (that can be used to display the gift card in the checkout for instance).
• Specify all the configurable options (rechargeability, single usage, behaviour when calculating taxes, etc.).

Once the gift card is created is possible to manage existing gift card using the Gift card app detail view. Here we can see the status, the balance, we can deactivate the gift card end edit it (screenshot of the editing view further below):

The Gift card app is also the go-to place for customer service operators as they can view all the details (including also the card recipient) in one single comprehensive view:

The gift card resource and API endpoint

Commerce Layer is an API-first platform, and gift cards are no exception.

The full API reference is available here.

Using the /api/gift_cards endpoint, you can create, read, update, and delete a gift_card resource. Write operations (create, update, and delete) can be executed using an integration token, while read operations will soon be available using a customer token (they're also readable using an integration token).

It's important to note that gift cards can also be used by external systems as long as an integration token is created and used to access the gift card endpoint.

Gift cards are omnichannel by nature, as they can be purchased online and used offline (and vice versa). Commerce Layer supports such use cases by exposing attributes and triggers like:

• _balance_change_cents — to update the balance of a gift card (after in-store usage, for instance).
• ._activate — to allow in-store activation.
• .balance_cents — to verify if the card has a positive balance.

This makes our gift card a viable solution even for brands that want to make their gift cards available to affiliates.

Gift card lifecycle

To better understand how gift cards work in Commerce Layer let’s give a look at the lifecycle of a gift card. For each action we’ll highlight details and main concepts and we’ll also share some best practices to make the most out of this great feature.

The diagram below shows the lifecycle of each type of gift card supported by Commerce Layer:

Creation

Gift cards can be created with this command:

This corresponds to the following API call:

Gift cards can be created either using a sales channel or an integration token, the former for standard website use, the latter could be a solution if you have a BFF.

Gift cards can be created in advance or on the fly (that is, when the customer wants to purchase one). The first option requires a BFF as you can't list gift cards with a sales channel token. The second is probably the best choice as it's more straightforward.

When you create a gift card, you can assign it to a recipient (i.e. the person that will receive the gift). To do so you can either add the gift_card.recipient_email attribute when creating the resource or patch the resource once created. The platform will automatically create a gift_card_recipient object and attach it to the gift card. If the customer email matches an existing customer the gift_card_recipient will have the relationship with the customer set.

Setting recipient_email on the gift_card resource is actually a shortcut to creating a gift_card_recipient resource and attaching it to the gift_card (if you do so you will see that gift_card.recipient_email will be populated with the email specified in the gift_card_recipient object).

A separate mention goes to physical gift cards: the best approach in this case is to import batches of gift card codes, along with balance and additional settings using imports. This is also the suggested approach to import third party generated gift cards.

Purchase

There are two scenarios related to gift card purchase whether you are purchasing a digital or a physical gift card.

Purchasing a digital gift card

Purchasing a digital gift card can be done contextually to the creation of the line item of an order. Let’s see the operations involved.

The first step is creating a gift card (if we don’t have pre-generated cards), this can be done as explained in the previous section.

Now that we have our gift card ( rMnaUzZRnX would be the ID in our case) we have to create a line item for it. So let’s create an order:

Now let’s create a line item of type gift_cards and attach it to the order:

So let’s review what we’ve done. We created a line_item resource in the same way we would have added a SKU, with the only difference of setting the item_type of the line_item to gift_cards (this is done implicitly when setting the relationship to the gift_card resource). No other operation is needed.

Purchasing a physical gift card

Purchasing digital gift cards is a slightly different matter as in this case we need a shipment for the physical card. There’s no out-of-the-box feature for physical gift card, but that’s not an issue, thanks to the flexibility of Commerce Layer we can easily code our way around this.

First of all we should create a sku for the gift card. The SKU should be mapped to the balance of the actual gift_card, so we’ll have SKUs matching the combination of balance and currencies (i.e. GIFT_CARD_50_USD, GIFT_CARD_100_EUR, and so on).

Here an example showing the sku for a 50 EUR gift card:

You can see in the inventory attribute that we have 100 pieces of the card available: as the gift card has to be batch-printed is very likely that we want to check the stock, otherwise (print on demand) we can simply flag them as “do not track stock”.

Now to purchase the physical card we have to do two things:

1. Create gift_card resource with amount corresponding to the price of the SKU (skus.prices.amount_cents).
2. Create a line_item resource with the SKU representing the desired gift card and attach the digital gift card to it.

The first is easily done:

For the second step let’s create a “standard” line item of type skus and add as metadata the ID of the gift card previously created:

We now have a shippable gift card associated to a digital gift_card resource!

Our philosophy is to give you building blocks rather than opinionated solutions and this is just an example (yet quite solid) of how to implement such use case. Another approach could be to rely on imports. In this case the approach would be:

1. A batch of gift cards is printed.
2. Generated codes, along with gift cards data are imported in Commerce Layer using (imports).
3. When a card is added to an order no association is done contextually (just the generic GIFT_CARD_50_EUR is added).
4. During fullfilment, the warehouse operator picks a card form the batch of newly printed cards and adds it to the parcel along with other products.
5. When the customer receives the box the gift card is ready to be used as is already imported in Commerce Layer (or can be used offline).

As shown in the state diagram at the beginning of this chapter, whether the gift card is physical or digital, its initial state after purchase is inactive. Let’s take a look at how to activate it — and how it can be used as a payment method.

Activation

Activating a gift card is as easy as going to the Gift cards app of the Dashboard and click the related button:

The above corresponds to hitting the /api/gift_cards endpoint and patching the card as active or, using the CLI, issuing the command below:

This flow is of course pretty simple (and manual). As usual here we leave space to your creativity without forcing any way of activating a gift card, but we still want to give some advice on how a solid activation process could look like.

You can create a webhook for order.place event and deploy a callback that, upon order placement will:

1. Get the line item containing the gift card and extract the gift_card_id (depending on how the gift card is being purchased this can be in the line_item linked resource or stored as a metadata).
2. Send an email to the customer that informs about the gift card and shows an activation link.
3. When the customer clicks on the link, some logic will patch the corresponding gift_card resource setting _activate=true

The gift card is now active and can be used to pay for an order.

Redemption

Not much to say indeed on redemption. Once you have an active gift card this can be used as a way to pay for an order, also in combination with a credit card or a wire transfer.

Commerce Layer hosted cart and checkout MFEs natively supports gift cards:

According to the status diagram in the beginning, if the balance is zero and the card is not rechargeable the gift card will enter the redeemed status.

Conclusion

Gift cards may seem like a simple feature on the surface, but Commerce Layer turns them into a flexible and powerful tool for modern commerce. With full API support, market-aware configuration, and a dedicated app for easy management, brands can issue, activate, and redeem gift cards across any channel — physical or digital, online or in-store.

Whether you’re launching a new gift card program or integrating an existing one, Commerce Layer provides the building blocks you need to tailor the experience to your business model. From refunds and customer rewards to promotional gifting and affiliate-ready setups, the possibilities are broad — and entirely under your control.

By thinking of gift cards not just as a payment method but as a strategic asset, you can unlock new value at every stage of the customer journey — while keeping your operations clean, global, and API-first.