Skip to main content
Skip to main content

Gift Cards

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

All hooks listed require 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

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.
Was this section helpful?