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

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

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.

---

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, but filtering the products with the is_giftcard flag:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

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

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

curl -L -X GET '<BACKEND_URL>/admin/products?is_giftcard=true' \
-H 'x-medusa-access-token: <API_TOKEN>'

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.

Create Gift Card Product

You can create a gift card product by sending a request to the Create a Product API Route:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

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

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

curl -L -X POST '<BACKEND_URL>/admin/products' \
-H 'x-medusa-access-token: <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"
            }
        ]
      }
    ]
}'

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

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

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

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

curl -L -X POST '<BACKEND_URL>/admin/products/<GIFT_CARD_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "description": "The best gift card"
}'

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

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

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

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

curl -L -X DELETE '<BACKEND_URL>/admin/products/<GIFT_CARD_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>'

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:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

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

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

curl -L -X GET '<BACKEND_URL>/admin/gift-cards' \
-H 'x-medusa-access-token: <API_TOKEN>'

This request doesn't require any parameters. It accepts parameters related to pagination, which you can check out in the API reference.

This request returns an array of gift_cards and pagination fields 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:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

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

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

curl -L -X POST '<BACKEND_URL>/admin/gift-cards' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "region_id": "<REGION_ID>",
    "value": 2000
}'

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

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

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

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

curl -L -X POST '<BACKEND_URL>/admin/gift-cards/<GIFT_CARD_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
    "balance": 2000
}'

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

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

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

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

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

curl -L -X DELETE '<BACKEND_URL>/admin/gift-card/<GIFT_CARD_ID>' \
-H 'x-medusa-access-token: <API_TOKEN>'

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