In this document, you’ll learn about Gift Cards and how they work in Medusa.
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
Product entity. A store can have only one gift card with unlimited denominations.
The gift card product has an attribute
is_giftcard set to
options property includes only one option, which is Denomination. The different denomination values are stored as
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:
code: a unique string of random characters. This is the code that the customer can use during their checkout to redeem the gift card.
value: The amount of the gift card. This is the amount the customer purchased, or was gifted in the case of custom gift cards.
balance: 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,
valuehave the same value.
is_disabled: A boolean value indicating whether a gift card is disabled or not.
ends_at: The expiry date and time of the gift card.
tax_rate: 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
- 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
- If the value of
Relations to Other Entities
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_id. You can access the region by expanding the
region relation and accessing
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_id. You can access the order by expanding the
order relation and accessing
You can also access the gift cards used in an order by expanding the
gift_cards relation on the order and accessing