Skip to main content

Gift Cards

In this document, you’ll learn about Gift Cards and how they work in Medusa.

Introduction​

Gift cards are products that customers can purchase and redeem in their future orders. Gift cards can have different amounts or denominations that a customer can choose from.

When a customer purchases a gift card, they should receive the code for the gift card by email or other type of notification. Then, they can use the code in their future purchases.

Gift Cards as Products​

Before a gift card is purchased, it’s essentially a ProductCopy to Clipboard entity. A store can have only one gift card with unlimited denominations.

The gift card product has an attribute is_giftcardCopy to Clipboard set to trueCopy to Clipboard. Its optionsCopy to Clipboard property includes only one option, which is Denomination. The different denomination values are stored as variantsCopy to Clipboard.

Once the customer purchases a gift card product, it is transformed into a usable gift card represented by the GiftCard entity.

Custom Gift Cards​

Aside from the gift card product, merchants can create usable gift cards and send directly to customers. These can be used as a reward sent to the customer or another form of discount.

As custom gift cards can be used once they’re created, they’re also represented by the GiftCard entity.

GiftCard Entity Overview​

Some of the GiftCard entity’s attributes are:

  • codeCopy to Clipboard: a unique string of random characters. This is the code that the customer can use during their checkout to redeem the gift card.
  • valueCopy to Clipboard: The amount of the gift card. This is the amount the customer purchased, or was gifted in the case of custom gift cards.
  • balanceCopy to Clipboard: The remaining amount of the gift card. If the customer uses the gift card on an order, and the order’s total does not exceed the amount available in the gift card, the remaining balance would be stored in this attribute. When the gift card is first created, balanceCopy to Clipboard and valueCopy to Clipboard have the same value.
  • is_disabledCopy to Clipboard: A boolean value indicating whether a gift card is disabled or not.
  • ends_atCopy to Clipboard: The expiry date and time of the gift card.
  • tax_rateCopy to Clipboard: The tax rate applied when calculating the totals of an order. The tax rate’s value is determined based on the following conditions:
    • If the value of region.gift_cards_taxableCopy to Clipboard is falseCopy to Clipboard, the tax_rateCopy to Clipboard is nullCopy to Clipboard;
    • Otherwise, if the merchant or admin user has manually set the value of the tax rate, it is applied;
    • Otherwise, if the region has a tax rate, it’s applied on the gift card. If not, the value of the tax rate is nullCopy to Clipboard.

Relations to Other Entities​

Region​

A gift card must belong to a region. When a customer purchases the gift card, the region they use to purchase the order is associated with the gift card.

For custom gift cards, the merchant specifies the region manually.

The ID of the region is stored in the attribute region_idCopy to Clipboard. You can access the region by expanding the regionCopy to Clipboard relation and accessing gift_card.regionCopy to Clipboard.

Order​

If the gift card was created because the customer purchased it, it is associated with the placed order.

The ID of the order is stored in the attribute order_idCopy to Clipboard. You can access the order by expanding the orderCopy to Clipboard relation and accessing gift_card.orderCopy to Clipboard.

You can also access the gift cards used in an order by expanding the gift_cardsCopy to Clipboard relation on the order and accessing order.gift_cardsCopy to Clipboard.

See Also​