medusa-store/docs/content/modules/gift-cards/storefront/use-gift-cards.mdx

---
description: 'Learn how to implement gift-card related functionalities in your storefront using the REST APIs. This includes showing the gift card to customers and redeeming the gift card during checkout.'
addHowToData: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# 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 the gift card product 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](../../../development/backend/install.mdx) 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 storefront](../../../starters/nextjs-medusa-starter.mdx).

### 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](../../../js-client/overview.md) and have [created an instance of the client](../../../js-client/overview.md#configuration).

### 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](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage).

For requests that use the cart, it's also assumed you already have [used CartProvider higher in your component tree](../../../medusa-react/overview.md#cartprovider).

### 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](../../carts-and-checkout/storefront/implement-checkout-flow.mdx) 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/store/#tag/Product/operation/GetProducts) endpoint, but passing it the `is_giftcard` query parameter:

<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>

```ts
medusa.products.list({
  is_giftcard: true,
})
.then(({ products, limit, offset, count }) => {
  if (products.length) {
    // gift card product exists
    const giftcard = products[0]
  } else {
    // no gift card product is created
  }
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

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

const GiftCard = () => {
  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 GiftCard
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

```ts
fetch(`<BACKEND_URL>/store/products?is_giftcard=true`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ products, limit, offset, count }) => {
  if (products.length) {
    // gift card product exists
    const giftcard = products[0]
  } else {
    // no gift card product is created
  }
})
```

</TabItem>
</Tabs>

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 product by setting it to `true`. To view other available parameters, check out the [API reference](/api/store/#tag/Product/operation/GetProducts)

The request returns the `products` array in the response, which holds the gift card in it, if it’s available. It also returns [pagination fields](/api/store/#section/Pagination).

### 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/store/#tag/Gift-Card/operation/GetGiftCardsCode) endpoint:

<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>

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

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useGiftCard } from "medusa-react"

const GiftCard = () => {
  const { gift_card, isLoading, isError } = useGiftCard("code")

  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
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

```ts
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
})
```

</TabItem>
</Tabs>

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](/api/store/#tag/Gift-Card/operation/GetGiftCardsCode).

---

## 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/store/#tag/Cart/operation/PostCartsCart) endpoint:

<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>

```ts
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
})
```

</TabItem>
<TabItem value="medusa-react" label="Medusa React">

```tsx
import { useCart } from "medusa-react"

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

  const { updateCart } = useCart()

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

  // ...
}

export default Cart
```

</TabItem>
<TabItem value="fetch" label="Fetch API">

```ts
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
})
```

</TabItem>
</Tabs>

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 in the update endpoint 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](#show-gft-card-details).

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.