docs: added gift card documentation guides (#2939)

docs/content/advanced/backend/gift-cards/index.md

@@ -0,0 +1,72 @@
+# 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 `Product` entity. A store can have only one gift card with unlimited denominations.
+
+The gift card product has an attribute `is_giftcard` set to `true`. Its `options` property includes only one option, which is Denomination. The different denomination values are stored as `variants`.
+
+Once the customer purchases a gift card product, it is transformed into a usable gift card represented by the [GiftCard entity](#giftcard-entity-overview).
+
+---
+
+## 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).
+
+---
+
+## GiftCard Entity Overview
+
+Some of the [GiftCard](../../../references/entities/classes/GiftCard.md) 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, `balance` and `value` have 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 `region.gift_cards_taxable` is `false`, the `tax_rate` is `null`;
+  - 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 `null`.
+
+---
+
+## 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_id`. You can access the region by expanding the `region` relation and accessing `gift_card.region`.
+
+### 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_id`. You can access the order by expanding the `order` relation and accessing `gift_card.order`.
+
+You can also access the gift cards used in an order by expanding the `gift_cards` relation on the order and accessing `order.gift_cards`.
+
+---
+
+## See Also
+
+- Gift cards [store](/api/store/#tag/Gift-Card) and [admin](/api/admin/#tag/Gift-Card) APIs
+- [How to manage gift cards using admin APIs](../../admin/manage-gift-cards.mdx)
+- [How to use gift cards in the storefront](../../storefront/use-gift-cards.mdx)
+- [How to send the customer a gift card](../../ecommerce/send-gift-card-to-customer.md)

docs/content/advanced/backend/notification/overview.md

@@ -1,4 +1,4 @@
-# Architecture Overview
+# Notification Architecture Overview
 
 This document gives an overview of the notification architecture and how it works.
 
@@ -93,4 +93,3 @@ An example of a flow that can be implemented using Medusa's Notification API is
 - [SendGrid Plugin](../../../add-plugins/sendgrid.mdx)
 - [Subscribers Overview](../subscribers/create-subscriber.md)
 - [Services Overview](../services/create-service.md)
-

docs/content/advanced/backend/subscribers/overview.md

@@ -22,6 +22,14 @@ Custom subscribers are TypeScript or JavaScript files in your project's `src/sub
 
 Whenever an event is emitted, the subscriber’s registered handler method is executed. The handler method receives as a parameter an object that holds data related to the event. For example, if an order is placed the `order.placed` event will be emitted and all the handlers will receive the order id in the parameter object.
 
+### Example Use Cases
+
+Subscribers are useful in many use cases, including:
+
+- Send a confirmation email to the customer when they place an order by subscribing to the `order.placed` event.
+- Automatically assign new customers to a customer group by subscribing to the `customer.created`.
+- Handle custom events that you emit
+
 ---
 
 ## See Also