Use Gift Cards on the Storefront

In this document, you’ll learn how to use gift cards on a storefront.

Overview

Customers can view and purchase gift card products. Then, customers can redeem the gift card in a future order.

Scenario

You want to implement the following features in a storefront:

• Show gift card products to the customer.
• View details of a gift card by its code.
• Redeem a gift card during checkout.

---

Prerequisites

Medusa Components

It's assumed that you already have a Medusa backend installed and set up. If not, you can follow the quickstart guide to get started.

It is also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install the Next.js Starter Template.

JS Client

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.

If you follow the JS Client code blocks, it’s assumed you already have Medusa’s JS Client installed and have created an instance of the client.

Medusa React

This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.

If you follow the Medusa React code blocks, it's assumed you already have Medusa React installed and have used MedusaProvider higher in your component tree.

For requests that use the cart, it's also assumed you already have used CartProvider higher in your component tree.

Previous Steps

To use gift cards, you must have a gift card created first. You can follow this documentation to learn how to do it using the admin APIs.

In addition, this document doesn't cover how to implement checkout functionality. You can follow this document to learn how to implement that.

---

Show the Gift Card Product

Customers should be able to view gift cards before they make the purchase. Gift cards are essentially products like any other.

You can retrieve the gift card product using the List Products API Route, but passing it the is_giftcard query parameter:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.products.list({
  is_giftcard: true,
})
.then(({ products, limit, offset, count }) => {
  if (products.length) {
    // gift card products exist
    
  } else {
    // no gift card products are created
  }
})

import { Product } from "@medusajs/medusa"
import { useProducts } from "medusa-react"

const GiftCards = () => {
  const { products, isLoading } = useProducts({
    is_giftcard: true,
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {products && products.length > 0 && (
        <ul>
          {products.map((product: Product) => (
            <li key={product.id}>{product.title}</li>
          ))}
        </ul>
      )}
      {products && !products.length && (
        <span>No Gift Cards</span>
      )}
    </div>
  )
}

export default GiftCards

fetch(`<BACKEND_URL>/store/products?is_giftcard=true`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ products, limit, offset, count }) => {
  if (products.length) {
    // gift card products exist
  } else {
    // no gift card products are created
  }
})

The request does not require any parameters. You can pass query parameters to filter the returned products.

You can use the is_giftcard query parameter to retrieve only the gift card products by setting its value to true. To view other available parameters, check out the API reference

The request returns the products array in the response, which holds the gift cards in it, if they're available. It also returns pagination fields.

Show Gift Card’s Denominations

The gift card’s denominations are available under the variants array. Each variant resembles a denomination.

The value of each denomination (or variant) is under the prices array. If you add the region_id query parameter, only prices for that specific regions are returned.

---

View Details of a Gift Card by Code

After the customer purchases the gift card, they’ll receive a code to redeem that gift card. Using that code, the customer can also view the details of that gift card.

You can retrieve the details of a gift card by sending a request to the Get Gift Card by Code API Route:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.giftCards.retrieve(code)
.then(({ gift_card }) => {
  console.log(gift_card.id)
})
.catch((e) => {
  // gift card doesn't exist or is disabled
})

import { useGiftCard } from "medusa-react"

type Props = {
  giftCardCode: string
}

const GiftCard = ({ giftCardCode }: Props) => {
  const { gift_card, isLoading, isError } = useGiftCard(
    giftCardCode
  )

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {gift_card && <span>{gift_card.value}</span>}
      {isError && <span>Gift Card does not exist</span>}
    </div>
  )
}

export default GiftCard

fetch(`<BACKEND_URL>/store/gift-cards/${code}`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ gift_card }) => {
  console.log(gift_card.id)
})
.catch((e) => {
  // gift card doesn't exist or is disabled
})

This request requires the code of the gift card passed as a path parameter.

It returns the gift card if it exists in the response. Otherwise, an error is returned.

Show Gift Card Details

In the returned gift card object, the following details can be shown to the customer:

• value: The amount of the gift card.
• balance: The remaining amount of the gift card. If the customer has previously used the gift card while purchasing an order but not its full value, this field shows how much is remaining in the card.
• ends_at: The expiry date and time of the gift card.

You can learn what other properties are available in the returned gift card object in the API reference.

---

Redeem Gift Card During Checkout

A customer can redeem more than one gift card during checkout. The cart’s totals will then be adjusted based on the applied gift card. The gift card’s amount isn’t actually used until the order is placed.

You can redeem a gift card during checkout by sending a request to the Update Cart API Route:

• Medusa JS Client
• Medusa React
• Fetch API

medusa.carts.update(cartId, {
  gift_cards: [
    {
      code,
    },
  ],
})
.then(({ cart }) => {
  console.log(cart.gift_cards.length)
})
.catch((e) => {
  // gift card doesn't exist or is disabled
})

import { useCart } from "medusa-react"

const Cart = () => {
  // ...

  const { updateCart } = useCart()

  const setGiftCard = (code: string) => {
    updateCart.mutate({
      gift_cards: [
        {
          code,
        },
      ],
    })
  }

  // ...
}

export default Cart

fetch(`<BACKEND_URL>/store/cart/${cartId}`, {
  method: "POST",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    gift_cards: [
      {
        code,
      },
    ],
  }),
})
.then((response) => response.json())
.then(({ cart }) => {
  console.log(cart.gift_cards.length)
})
.catch((e) => {
  // gift card doesn't exist or is disabled
})

This request requires the ID of the cart as a path parameter. It allows passing any cart property you want to update in its body parameters.

To add gift cards, you must pass the array gift_cards. Each item in the array should be an object having the property code, with its value being the code of the gift card to apply.

Tip

The parameters passed to the update API Route replace existing values. So, if you previously added a gift card, then tried adding another, you must include both in the gift_cards array.

This request returns the card object in the response.

Show Gift Card Details in the Cart

You can show the details of the applied gift cards by accessing cart.gift_cards. Its attributes are similar to those explained in the previous section.

You can also use the following properties to display changes on the cart’s totals:

• gift_card_total: The total amount applied by all the gift cards.
• gift_card_tax_total: The total tax applied for all gift cards.