medusa-store/www/apps/docs/content/modules/gift-cards/admin/manage-gift-cards.mdx

---
description: 'Learn how to implement gift card functionalities for admins using the REST APIs. This includes how to create, update, and delete gift cards, as well as custom gift cards.'
addHowToData: true
---

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

# How to Manage Gift Cards

In this document, you’ll learn how to manage gift cards using the admin APIs.

:::note

You can learn more about what gift cards are and how they’re used in [this documentation](../gift-cards.md)

:::

## Overview

Using the gift cards’ admin APIs, you can manage gift cards including listing, updating, and deleting them.

### Scenario

You want to add or use the following admin functionalities:

- Manage gift card products including retrieving, adding, updating, and deleting them.
- Managing custom gift cards including retrieving, adding, updating and deleting them.

---

## Prerequisites

### Medusa Components

It is 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.

### 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](../../../js-client/overview.mdx) installed and have [created an instance of the client](../../../js-client/overview.mdx#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.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#usage).

### Authenticated Admin User

You must be an authenticated admin user before following along with the steps in the tutorial.

You can learn more about [authenticating as an admin user in the API reference](https://docs.medusajs.com/api/admin#authentication).

---

## Manage Gift Card Product

This section covers managing the gift card products. Each gift card can have unlimited denominations.

As gift cards are, before purchase, essentially products, you’ll be using product API Routes to manage them.

### Retrieve Gift Card Product

You can retrieve the gift card products by sending a request to the [List Products API Route](https://docs.medusajs.com/api/admin#products_getproducts), but filtering the products with the `is_giftcard` flag:

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

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

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

    ```tsx
    import { Product } from "@medusajs/medusa"
    import { 
      PricedProduct,
    } from "@medusajs/medusa/dist/types/pricing"
    import { useAdminProducts } from "medusa-react"

    const GiftCard = () => {
      const { products, isLoading } = useAdminProducts({
        is_giftcard: true,
      })

      return (
        <div>
          {isLoading && <span>Loading...</span>}
          {products && products.length > 0 && (
            <ul>
              {products.map(
                (product: (Product | PricedProduct)) => (
                  <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>/admin/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
      }
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X GET '<BACKEND_URL>/admin/products?is_giftcard=true' \
    -H 'Authorization: Bearer <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

The List Products API Route accepts a variety of query parameters that can be used to filter the products. One of them is `is_giftcard`. When set to `true`, it will only retrieve the gift card products.

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](https://docs.medusajs.com/api/admin#pagination).

### Create Gift Card Product

You can create a gift card product by sending a request to the [Create a Product API Route](https://docs.medusajs.com/api/admin#products_postproducts):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    import { ProductStatus } from "@medusajs/medusa"
    // ...

    medusa.admin.products.create({
      title: "My Gift Card",
      is_giftcard: true,
      discountable: false,
      status: ProductStatus.PUBLISHED,
      options: [
        {
          title: "Denomination",
        },
      ],
      variants: [
        {
          title: "1",
          inventory_quantity: 0,
          manage_inventory: false,
          prices: [
              {
                  amount: 2000,
                  currency_code: "usd",
              },
          ],
          options: [
              {
                  value: "2000",
              },
          ],
        },
      ],
    })
    .then(({ product }) => {
      console.log(product.id)
    })
    ```

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

    ```tsx
    import { useAdminCreateProduct } from "medusa-react"
    import { ProductStatus } from "@medusajs/medusa"

    const CreateGiftCard = () => {
      const createGiftCard = useAdminCreateProduct()
      // ...

      const handleCreate = () => {
        createGiftCard.mutate({
          title: "My Gift Card",
          is_giftcard: true,
          discountable: false,
          status: ProductStatus.PUBLISHED,
          options: [
            {
              title: "Denomination",
            },
          ],
          variants: [
            {
              title: "1",
              inventory_quantity: 0,
              manage_inventory: false,
              prices: [
                  {
                      amount: 2000,
                      currency_code: "usd",
                  },
              ],
              options: [
                  {
                      value: "2000",
                  },
              ],
            },
          ],
        })
      }

      // ...
    }

    export default CreateGiftCard
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/products`, {
      method: "POST",
      credentials: "include",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        title: "My Gift Card",
        is_giftcard: true,
        discountable: false,
        status: "published",
        options: [
          {
            title: "Denomination",
          },
        ],
        variants: [
          {
            title: "1",
            inventory_quantity: 0,
            manage_inventory: false,
            prices: [
                {
                    amount: 2000,
                    currency_code: "usd",
                },
            ],
            options: [
                {
                    value: "2000",
                },
            ],
          },
        ],
      }),
    })
    .then((response) => response.json())
    .then(({ product }) => {
      console.log(product.id)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/products' \
    -H 'Authorization: Bearer <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "title": "My Gift Card",
        "is_giftcard": true,
        "discountable": false,
        "status": "published",
        "options": [
          {
            "title": "Denomination"
          }
        ],
        "variants": [
          {
            "title": "1",
            "inventory_quantity": 0,
            "manage_inventory": false,
            "prices": [
                {
                    "amount": 2000,
                    "currency_code": "usd"
                }
            ],
            "options": [
                {
                    "value": "2000"
                }
            ]
          }
        ]
    }'
    ```

  </TabItem>
</Tabs>

This request requires the `title` body parameter, which is the name given to the gift card. To add the gift card product, you need to supply the following parameters:

- `is_giftcard` set to `true`.
- `discountable` set to `false`. It indicates that discounts don’t apply on this product.
- `status`: a string indicating the status of the product. Can be `published`, `draft`, `proposed`, or `rejected`.
- `options`: An array that includes available options of the product. For a gift card, you should add one option with the title “Denomination”.
- `variants`: An array that includes the different variations of the product using the available options. For a gift card, you should pass each denomination value as an item in this array. The value is passed in the `prices` and `options` array. If you want to add prices for different currencies, you can pass them under `prices` and `options` as well.

You can pass other body parameters to change the handle, add images, and more. Check the [API reference](https://docs.medusajs.com/api/admin#products_postproducts) for available body parameters.

This request returns the created gift card product in the response.

:::tip

Although you can create an unlimited number of gift cards, the admin dashboard's UI only shows one gift card.

:::

### Update Gift Card Product

After creating a gift card, merchants can update it or its denomination.

You can update a gift card product’s details by sending a request to the [Update a Product API Route](https://docs.medusajs.com/api/admin#products_postproductsproduct):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.products.update(giftCardId, {
      description: "The best gift card",
    })
    .then(({ product }) => {
      console.log(product.id)
    })
    ```

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

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

    type Props = {
      giftCardId: string
    }

    const GiftCard = ({
      giftCardId
    }: Props) => {
      const updateGiftCard = useAdminUpdateProduct(giftCardId)
      // ...

      const handleUpdate = () => {
        updateGiftCard.mutate({
          description: "The best gift card",
        }, {
          onSuccess: ({ product }) => {
            console.log(product.description)
          }
        })
      }

      // ...
    }

    export default GiftCard
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/products/${giftCardId}`, {
      method: "POST",
      credentials: "include",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        description: "The best gift card",
      }),
    })
    .then((response) => response.json())
    .then(({ product }) => {
      console.log(product.id)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/products/<GIFT_CARD_ID>' \
    -H 'Authorization: Bearer <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "description": "The best gift card"
    }'
    ```

  </TabItem>
</Tabs>

This request requires the ID of the gift card product as a path parameter. You can pass in its body parameters, any of the gift card’s properties to update.

In this example, you update the description of the gift card. You can check the [API reference](https://docs.medusajs.com/api/admin#products_postproductsproduct) for all the body parameters you can pass to this request.

This request returns the updated gift card product in the response.

### Delete Gift Card Product

You can delete a gift card product by sending a request to the [Delete a Product API Route](https://docs.medusajs.com/api/admin#products_deleteproductsproduct):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.products.delete(giftCardId)
    .then(({ id, object, deleted }) => {
      console.log(id)
    })
    ```

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

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

    type Props = {
      giftCardId: string
    }

    const GiftCard = ({ giftCardId }: Props) => {
      const deleteGiftCard = useAdminDeleteProduct(giftCardId)
      // ...

      const handleDelete = () => {
        deleteGiftCard.mutate(void 0, {
          onSuccess: ({ id, object, deleted }) => {
            console.log(id)
          }
        })
      }

      // ...
    }

    export default GiftCard
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/products/${giftCardId}`, {
      method: "DELETE",
      credentials: "include",
    })
    .then((response) => response.json())
    .then(({ id, object, deleted }) => {
      console.log(id)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X DELETE '<BACKEND_URL>/admin/products/<GIFT_CARD_ID>' \
    -H 'Authorization: Bearer <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

This request requires the ID of the gift card product as a path parameter.

It returns the following fields in the response:

- `id`: The ID of the deleted gift card.
- `object`: A string indicating the type of object deleted. By default, its value is `product`.
- `deleted`: A boolean value indicating whether the gift card was deleted or not.

---

## Manage Custom Gift Cards

This section covers how to manage custom gift cards. You can create an unlimited number of custom gift cards.

### List Custom Gift Cards

You can retrieve all custom gift cards by sending a request to the [List Gift Cards API Route](https://docs.medusajs.com/api/admin#gift-cards_getgiftcards):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.giftCards.list()
    .then(({ gift_cards, limit, offset, count }) => {
      console.log(gift_cards.length)
    })
    ```

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

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

    const CustomGiftCards = () => {
      const { gift_cards, isLoading } = useAdminGiftCards()
      
      return (
        <div>
          {isLoading && <span>Loading...</span>}
          {gift_cards && !gift_cards.length && (
            <span>No custom gift cards...</span>
          )}
          {gift_cards && gift_cards.length > 0 && (
            <ul>
              {gift_cards.map((giftCard) => (
                <li key={giftCard.id}>{giftCard.code}</li>
              ))}
            </ul>
          )}
        </div>
      )
    }

    export default CustomGiftCards
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/gift-cards`, {
      credentials: "include",
    })
    .then((response) => response.json())
    .then(({ gift_cards, limit, offset, count }) => {
      console.log(gift_cards.length)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X GET '<BACKEND_URL>/admin/gift-cards' \
    -H 'Authorization: Bearer <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

This request doesn't require any parameters. It accepts parameters related to pagination, which you can check out in the [API reference](https://docs.medusajs.com/api/admin#gift-cards_getgiftcards).

This request returns an array of `gift_cards` and [pagination fields](https://docs.medusajs.com/api/admin#pagination) in the response.

### Create a Custom Gift Card

Merchants can create custom gift cards to send a reward or gift to the customer.

You can create a custom gift card by sending a request to the [Create a Gift Card API Route](https://docs.medusajs.com/api/admin#gift-cards_postgiftcards):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.giftCards.create({
      region_id,
      value,
    })
    .then(({ gift_card }) => {
      console.log(gift_card.id)
    })
    ```

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

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

    const CreateCustomGiftCards = () => {
      const createGiftCard = useAdminCreateGiftCard()
      // ...
      
      const handleCreate = (
        regionId: string, 
        value: number
      ) => {
        createGiftCard.mutate({
          region_id: regionId,
          value,
        }, {
          onSuccess: ({ gift_card }) => {
            console.log(gift_card.id)
          }
        })
      }

      // ...
    }

    export default CreateCustomGiftCards
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/gift-cards`, {
      method: "POST",
      credentials: "include",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        region_id,
        value,
      }),
    })
    .then((response) => response.json())
    .then(({ gift_card }) => {
      console.log(gift_card.id)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/gift-cards' \
    -H 'Authorization: Bearer <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "region_id": "<REGION_ID>",
        "value": 2000
    }'
    ```

  </TabItem>
</Tabs>

This request requires the `region_id` body parameter. Its value should be the ID of the region that this gift card can be used in.

It optionally accepts other body parameters, including the `value` parameter, which is the amount of the gift card. You can check the [API reference](https://docs.medusajs.com/api/admin#gift-cards_postgiftcards) for the rest of the body parameters.

This request returns the created gift card object in the response.

### Update Custom Gift Card

Merchants can update any of the gift card’s properties, except for the value of the gift card.

You can update a gift card by sending a request to the [Update a Gift Card API Route](https://docs.medusajs.com/api/admin#gift-cards_postgiftcardsgiftcard):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.giftCards.update(giftCardId, {
      balance,
    })
    .then(({ gift_card }) => {
      console.log(gift_card.id)
    })
    ```

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

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

    type Props = {
      customGiftCardId: string
    }

    const CustomGiftCard = ({ customGiftCardId }: Props) => {
      const updateGiftCard = useAdminUpdateGiftCard(
        customGiftCardId
      )
      // ...
      
      const handleUpdate = (regionId: string) => {
        updateGiftCard.mutate({
          region_id: regionId,
        })
      }

      // ...
    }

    export default CustomGiftCard
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/gift-cards/${giftCardId}`, {
      method: "POST",
      credentials: "include",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        balance,
      }),
    })
    .then((response) => response.json())
    .then(({ gift_card }) => {
      console.log(gift_card.id)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X POST '<BACKEND_URL>/admin/gift-cards/<GIFT_CARD_ID>' \
    -H 'Authorization: Bearer <API_TOKEN>' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "balance": 2000
    }'
    ```

  </TabItem>
</Tabs>

This request requires the ID of the gift card as a path parameter. It accepts in its body parameters the gift card’s properties that you want to update.

In this example, you update the balance of the gift card. The balance is the remaining amount in the gift card that the customer can use. You can check the [API reference](https://docs.medusajs.com/api/admin#gift-cards_postgiftcardsgiftcard) to learn what other parameters are allowed.

This request returns the updated gift card object in the response.

### Delete Custom Gift Card

You can delete a custom gift card by sending a request to the [Delete a Gift Card API Route](https://docs.medusajs.com/api/admin#gift-cards_deletegiftcardsgiftcard):

<Tabs groupId="request-type" isCodeTabs={true}>
  <TabItem value="client" label="Medusa JS Client" default>

    ```ts
    medusa.admin.giftCards.delete(giftCardId)
    .then(({ id, object, deleted }) => {
      console.log(id)
    })
    ```

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

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

    type Props = {
      customGiftCardId: string
    }

    const CustomGiftCard = ({ customGiftCardId }: Props) => {
      const deleteGiftCard = useAdminDeleteGiftCard(
        customGiftCardId
      )
      // ...
      
      const handleDelete = () => {
        deleteGiftCard.mutate(void 0, {
          onSuccess: ({ id, object, deleted}) => {
            console.log(id)
          }
        })
      }

      // ...
    }

    export default CustomGiftCard
    ```

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

    ```ts
    fetch(`<BACKEND_URL>/admin/gift-cards/${giftCardId}`, {
      method: "DELETE",
      credentials: "include",
    })
    .then((response) => response.json())
    .then(({ id, object, deleted }) => {
      console.log(id)
    })
    ```

  </TabItem>
  <TabItem value="curl" label="cURL">

    ```bash
    curl -L -X DELETE '<BACKEND_URL>/admin/gift-card/<GIFT_CARD_ID>' \
    -H 'Authorization: Bearer <API_TOKEN>'
    ```

  </TabItem>
</Tabs>

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

It returns the following fields in the response:

- `id`: The ID of the deleted gift card.
- `object`: A string indicating the type of object deleted. By default, its value is `gift-card`.
- `deleted`: A boolean value indicating whether the gift card was deleted or not.

---

## See Also

- [Use gift cards on the storefront](../storefront/use-gift-cards.mdx)