Gift Cards

Queries and Mutations listed here are used to send requests to the Admin Gift Card API Routes.

All hooks listed require user authentication.

Admins can create gift cards and send them directly to customers, specifying options like their balance, region, and more. These gift cards are different than the saleable gift cards in a store, which are created and managed through useAdminCreateProduct.

Related Guide: How to manage gift cards.

Mutations

useAdminCreateGiftCard

This hook creates a gift card that can redeemed by its unique code. The Gift Card is only valid within one region.

Example

import React from "react"
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

Mutation Function Parameters

AdminPostGiftCardsReqAdminPostGiftCardsReqRequired

The details of the gift card to create.

Mutation Function Returned Data

AdminGiftCardsResAdminGiftCardsResRequired

The gift card's details.

useAdminUpdateGiftCard

This hook updates a gift card's details.

Example

import React from "react"
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,
    }, {
      onSuccess: ({ gift_card }) => {
        console.log(gift_card.id)
      }
    })
  }

  // ...
}

export default CustomGiftCard

Hook Parameters

idstringRequired

The gift card's ID.

Mutation Function Parameters

AdminPostGiftCardsGiftCardReqAdminPostGiftCardsGiftCardReqRequired

The details to update of the gift card.

Mutation Function Returned Data

AdminGiftCardsResAdminGiftCardsResRequired

The gift card's details.

useAdminDeleteGiftCard

This hook deletes a gift card. Once deleted, it can't be used by customers.

Example

import React from "react"
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

Hook Parameters

idstringRequired

The gift card's ID.

Mutation Function Returned Data

DeleteResponseDeleteResponseRequired

The response returned for a DELETE request.

---

Queries

useAdminGiftCards

This hook retrieves a list of gift cards. The gift cards can be filtered by fields such as q passed in the query parameter. The gift cards can also paginated.

Example

To list gift cards:

import React from "react"
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

By default, only the first 50 records are retrieved. You can control pagination by specifying the limit and offset properties:

import React from "react"
import { useAdminGiftCards } from "medusa-react"

const CustomGiftCards = () => {
  const { 
    gift_cards, 
    limit,
    offset,
    isLoading
  } = useAdminGiftCards({
    limit: 20,
    offset: 0
  })
  
  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

Hook Parameters

queryAdminGetGiftCardsParams

Filters and pagination configurations to apply on the retrieved gift cards.

Query Returned Data

limitnumberRequired

The maximum number of items that can be returned in the list.

offsetnumberRequired

The number of items skipped before the returned items in the list.

countnumberRequired

The total number of items available.

gift_cardsGiftCard[]Required

The list of gift cards.

useAdminGiftCard

This hook retrieves a gift card's details.

Example

import React from "react"
import { useAdminGiftCard } from "medusa-react"

type Props = {
  giftCardId: string
}

const CustomGiftCard = ({ giftCardId }: Props) => {
  const { gift_card, isLoading } = useAdminGiftCard(giftCardId)
  
  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {gift_card && <span>{gift_card.code}</span>}
    </div>
  )
}

export default CustomGiftCard

Hook Parameters

idstringRequired

The gift card's ID.

Query Returned Data

gift_cardGiftCardRequired

A gift card's details.