chore: merge docs from master to develop (#3650)
* Fix issue on fixed total amount discount when using includes tax (#3472) The calculation of the fixed discount amount breaks when having includes_tax setting active, due to the line item totals are incorrect and returning everything as 0, thus the totalItemPercentage will be Infinitiy due to the division by a subtotal of 0 * chore: Add missing changeset for @medusajs/medusa * feat(medusa): Improve performance of Products domain (#3417) * feat(medusa): Improve product update performances * fix tests and update * update mock repo * improve repo * cleanup * fix * cleanup + bulk emit + unit test fix * improvements * improve * fix unit tests * fix export * fix product update handler * enhance mock repo * fix import integration * fix end point tests * revert mock repo product variant * fix unit * cleanup * cleanup * address feedback * fix quotes in tests * address feedback * Create new-tips-mate.md * use types * chore: Remove integration-tests from changeset * chore(release): v1.7.14 * chore(docs): Generated Docs Announcement Bar (automated) (#3489) Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com> * fix(medusa): EventBusService.emit using Redis mock (#3491) * Fix eventBusService.emit using redis mock * revert gitignore * enqueuer * unit test add redis_url * fix test * chore(docs): Generated Services Reference (automated) (#3490) Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com> * docs: publish restructure (#3496) * docs: added features and guides overview page * added image * added version 2 * added version 3 * added version 4 * docs: implemented new color scheme * docs: redesigned sidebar (#3193) * docs: redesigned navbar for restructure (#3199) * docs: redesigned footer (#3209) * docs: redesigned cards (#3230) * docs: redesigned admonitions (#3231) * docs: redesign announcement bar (#3236) * docs: redesigned large cards (#3239) * docs: redesigned code blocks (#3253) * docs: redesigned search modal and page (#3264) * docs: redesigned doc footer (#3268) * docs: added new sidebars + refactored css and assets (#3279) * docs: redesigned api reference sidebar * docs: refactored css * docs: added code tabs transition * docs: added new sidebars * removed unused assets * remove unusued assets * Fix deploy errors * fix incorrect link * docs: fixed code responsivity + missing icons (#3283) * docs: changed icons (#3296) * docs: design fixes to the sidebar (#3297) * redesign fixes * docs: small design fixes * docs: several design fixes after restructure (#3299) * docs: bordered icon fixes * docs: desgin fixes * fixes to code blocks and sidebar scroll * design adjustments * docs: restructured homepage (#3305) * docs: restructured homepage * design fixes * fixed core concepts icon * docs: added core concepts page (#3318) * docs: restructured homepage * design fixes * docs: added core concepts page * changed text of different components * docs: added architecture link * added missing prop for user guide * docs: added regions overview page (#3327) * docs: added regions overview * moved region pages to new structure * docs: fixed description of regions architecture page * small changes * small fix * docs: added customers overview page (#3331) * docs: added regions overview * moved region pages to new structure * docs: fixed description of regions architecture page * small changes * small fix * docs: added customers overview page * fix link * resolve link issues * docs: updated regions architecture image * docs: second-iteration fixes (#3347) * docs: redesigned document * design fixes * docs: added products overview page (#3354) * docs: added carts overview page (#3363) * docs: added orders overview (#3364) * docs: added orders overview * added links in overview * docs: added vercel redirects * docs: added soon badge for cards (#3389) * docs: resolved feedback changes + organized troubleshooting pages (#3409) * docs: resolved feedback changes * added extra line * docs: changed icons for restructure (#3421) * docs: added taxes overview page (#3422) * docs: added taxes overview page * docs: fix sidebar label * added link to taxes overview page * fixed link * docs: fixed sidebar scroll (#3429) * docs: added discounts overview (#3432) * docs: added discounts overview * fixed links * docs: added gift cards overview (#3433) * docs: added price lists overview page (#3440) * docs: added price lists overview page * fixed links * docs: added sales channels overview page (#3441) * docs: added sales overview page * fixed links * docs: added users overview (#3443) * docs: fixed sidebar border height (#3444) * docs: fixed sidebar border height * fixed svg markup * docs: added possible solutions to feedback component (#3449) * docs: added several overview pages + restructured files (#3463) * docs: added several overview pages * fixed links * docs: added feature flags + PAK overview pages (#3464) * docs: added feature flags + PAK overview pages * fixed links * fix link * fix link * fixed links colors * docs: added strategies overview page (#3468) * docs: automated upgrade guide (#3470) * docs: automated upgrade guide * fixed vercel redirect * docs: restructured files in docs codebase (#3475) * docs: restructured files * docs: fixed eslint exception * docs: finished restructure loose-ends (#3493) * fixed uses of backend * docs: finished loose ends * eslint fixes * fixed links * merged master * added update instructions for v1.7.12 * docs: fixed discount details (#3499) * docs: fix trailing slash causing 404 (#3508) * docs: fix error during navigation (#3509) * docs: removed the gatsby storefront guide (#3527) * docs: removed the gatsby storefront guide * docs: fixed query value * chore(docs): Removed Docs Announcement Bar (automated) (#3536) Co-authored-by: shahednasser <shahednasser@users.noreply.github.com> * fix(medusa): Variant update should include the id for the listeners to be able to identify the entity (#3539) * fix(medusa): Variant update should include the id for the listeners to be able to identify the entity * fix unit tests * Create brave-seahorses-film.md * docs: fix admin redirects (#3548) * chore(release): v1.7.15 * chore(docs): Generated Docs Announcement Bar (automated) (#3550) Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com> * chore(docs): Generated Services Reference (automated) (#3551) Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com> * chore: updated READMEs of plugins (#3546) * chore: updated READMEs of plugins * added notice to plugins * docs: added a deploy guide for next.js storefront (#3558) * docs: added a deploy next.js guide * docs: fix image zoom * docs: fixes to next.js deployment guide to vercel (#3562) * chore(workflows): Enable manual workflow in pre-release mode (#3566) * chore(docs): Removed Docs Announcement Bar (automated) (#3598) Co-authored-by: shahednasser <shahednasser@users.noreply.github.com> * fix(medusa): Rounding issues on line item adjustments (#3446) * chores(medusa): Attempt to fix discount rounding issues * add migration * update entities * apply multipler factor properly * fix discount service * WIP * fix rounding issues in discounts * fix some tests * Exclude raw_discount_total from responses * fix adjustments * cleanup response * fix * fix draft order integration * fix order integration * fix order integration * address feedback * fix test * Create .changeset/polite-llamas-sit.md * remove comment --------- Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com> * chore(workflows): Add release notification (#3629) --------- Co-authored-by: pepijn-vanvlaanderen <pepijn@webbers.com> Co-authored-by: olivermrbl <oliver@mrbltech.com> Co-authored-by: Adrien de Peretti <adrien.deperetti@gmail.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com> Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com> Co-authored-by: shahednasser <shahednasser@users.noreply.github.com> Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>
This commit is contained in:
Shahed Nasser
co-authored by
olivermrbl
shahednasser
Oliver Windall Juhl
pepijn-vanvlaanderen
olivermrbl
Adrien de Peretti
github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Carlos R. L. Rodrigues
olivermrbl
shahednasser
Oliver Windall Juhl
pepijn-vanvlaanderen
olivermrbl
Adrien de Peretti
github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Carlos R. L. Rodrigues
parent
e6b5859af2
commit
6f1b49af03
@@ -0,0 +1,815 @@
|
||||
---
|
||||
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 the gift card product including retrieving, adding, updating, and deleting it.
|
||||
- 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.md) installed 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).
|
||||
|
||||
### 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](/api/admin/#section/Authentication).
|
||||
|
||||
---
|
||||
|
||||
## Manage Gift Card Product
|
||||
|
||||
This section covers managing the gift card product. There can only be one gift card product in a store. The gift card can have unlimited denominations.
|
||||
|
||||
As gift cards are, before purchase, essentially products, you’ll be using product endpoints to manage them.
|
||||
|
||||
### Retrieve Gift Card Product
|
||||
|
||||
You can retrieve the gift card product by sending a request to the [List Products](/api/admin/#tag/Product/operation/GetProducts) endpoint, but filtering by the `is_giftcard` flag:
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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 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 {
|
||||
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 product exists
|
||||
const giftcard = products[0]
|
||||
} else {
|
||||
// no gift card product is 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 endpoint 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 product.
|
||||
|
||||
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/admin/#section/Pagination).
|
||||
|
||||
### Create Gift Card Product
|
||||
|
||||
You can create only one gift card product in a store. To create a gift card product, send a request to the [Create a Product](/api/admin/#tag/Product/operation/PostProducts) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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](/api/admin/#tag/Product/operation/PostProducts) for available body parameters.
|
||||
|
||||
This request returns the created gift card product in the response.
|
||||
|
||||
### 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/admin/#tag/Product/operation/PostProductsProduct) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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"
|
||||
|
||||
const UpdateGiftCard = () => {
|
||||
const createGiftCard = useAdminUpdateProduct(giftCardId)
|
||||
// ...
|
||||
|
||||
const handleUpdate = () => {
|
||||
createGiftCard.mutate({
|
||||
description: "The best gift card",
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default UpdateGiftCard
|
||||
```
|
||||
|
||||
</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](/api/admin/#tag/Product/operation/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 the gift card product by sending a request to the [Delete a Product](/api/admin/#tag/Product/operation/DeleteProductsProduct) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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"
|
||||
|
||||
const GiftCard = () => {
|
||||
const deleteGiftCard = useAdminDeleteProduct(giftCardId)
|
||||
// ...
|
||||
|
||||
const handleDelete = () => {
|
||||
deleteGiftCard.mutate()
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
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/admin/#tag/Gift-Card/operation/GetGiftCards) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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 { GiftCard } from "@medusajs/medusa"
|
||||
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: 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 does not require any parameters. It accepts parameters related to pagination, which you can check out in the [API reference](/api/admin/#tag/Gift-Card/operation/GetGiftCards).
|
||||
|
||||
This request returns an array of `gift_cards` and [pagination fields](/api/admin/#section/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/admin/#tag/Gift-Card/operation/PostGiftCards) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
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](/api/admin/#tag/Gift-Card/operation/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/admin/#tag/Gift-Card/operation/PostGiftCardsGiftCard) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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"
|
||||
|
||||
const UpdateCustomGiftCards = () => {
|
||||
const updateGiftCard = useAdminUpdateGiftCard(
|
||||
customGiftCardId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleUpdate = (regionId: string) => {
|
||||
updateGiftCard.mutate({
|
||||
region_id: regionId,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default UpdateCustomGiftCards
|
||||
```
|
||||
|
||||
</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](/api/admin/#tag/Gift-Card/operation/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/admin/#tag/Gift-Card/operation/DeleteGiftCardsGiftCard) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" wrapperClassName="code-tabs">
|
||||
<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"
|
||||
|
||||
const CustomGiftCard = () => {
|
||||
const deleteGiftCard = useAdminDeleteGiftCard(
|
||||
customGiftCardId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleDelete = () => {
|
||||
deleteGiftCard.mutate()
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
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)
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
description: 'Learn how to send a gift card code to the customer. Once the customer purchases a gift card, an email can be sent with the code so that they can redeem the gift card.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# How to Send Gift Card Code to Customer
|
||||
|
||||
In this document, you’ll learn how to send a customer the gift card code they purchased.
|
||||
|
||||
## Overview
|
||||
|
||||
Once the customer purchases a gift card, they should receive the code of the gift card so that they can use it in future purchases.
|
||||
|
||||
Typically, the code would be sent by email, however, you’re free to choose how you deliver the gift card code to the customer.
|
||||
|
||||
This document shows you how to track when a gift card has been purchased so that you can send its code to the customer.
|
||||
|
||||
:::tip
|
||||
|
||||
You can alternatively use the [SendGrid](../../../plugins/notifications/sendgrid.mdx) plugin, which handles sending the email automatically.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
### Redis
|
||||
|
||||
Redis is required for batch jobs to work. Make sure you [install Redis](../../../development/backend/prepare-environment.mdx#redis) and [configure it with the Medusa backend](../../../development/backend/configurations.md#redis).
|
||||
|
||||
### Notification Provider
|
||||
|
||||
To send an email or another type of notification method, you must have a notification provider installed or configured. You can either install an existing plugin or [create your own](../../../development/notification/create-notification-provider.md).
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create a Subscriber
|
||||
|
||||
To subscribe to and handle an event, you must create a subscriber.
|
||||
|
||||
:::info
|
||||
|
||||
You can learn more about subscribers in the [Subscribers](../../../development/events/subscribers.mdx) documentation.
|
||||
|
||||
:::
|
||||
|
||||
Create the file `src/subscribers/gift-card.ts` with the following content:
|
||||
|
||||
```ts title=src/subscribers/gift-card.ts
|
||||
type InjectedDependencies = {
|
||||
// TODO add necessary dependencies
|
||||
}
|
||||
|
||||
class GiftCardSubscriber {
|
||||
constructor(container: InjectedDependencies) {
|
||||
// TODO subscribe to event
|
||||
}
|
||||
}
|
||||
|
||||
export default GiftCardSubscriber
|
||||
```
|
||||
|
||||
You’ll be adding in the next step the necessary dependencies to the subscriber.
|
||||
|
||||
:::info
|
||||
|
||||
You can learn more about [dependency injection](../../../development/fundamentals/dependency-injection.md) in this documentation.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Subscribe to the Event
|
||||
|
||||
In this step, you’ll subscribe to the event `gift_card.created` to send the customer a notification about their gift card.
|
||||
|
||||
There are two ways to do this:
|
||||
|
||||
### Method 1: Using the NotificationService
|
||||
|
||||
If the notification provider you’re using already implements the logic to handle this event, you can subscribe to the event using the `NotificationService`:
|
||||
|
||||
```ts title=src/subscribers/gift-card.ts
|
||||
import { NotificationService } from "@medusajs/medusa"
|
||||
|
||||
type InjectedDependencies = {
|
||||
notificationService: NotificationService
|
||||
}
|
||||
|
||||
class GiftCardSubscriber {
|
||||
constructor({ notificationService }: InjectedDependencies) {
|
||||
notificationService.subscribe(
|
||||
"gift_card.created",
|
||||
"<NOTIFICATION_PROVIDER_IDENTIFIER>"
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
export default GiftCardSubscriber
|
||||
```
|
||||
|
||||
Where `<NOTIFICATION_PROVIDER_IDENTIFIER>` is the identifier for your notification provider. For example, if you’re using SendGrid, the identifier is `sendgrid`.
|
||||
|
||||
:::info
|
||||
|
||||
You can learn more about handling events with the Notification Service using [this documentation](../../../development/notification/create-notification-provider.md).
|
||||
|
||||
:::
|
||||
|
||||
### Method 2: Using the EventBusService
|
||||
|
||||
If the notification provider you’re using isn’t configured to handle this event, or you want to implement some other custom logic, you can subscribe to the event using the `EventBusService`:
|
||||
|
||||
```ts title=src/subscribers/gift-card.ts
|
||||
import {
|
||||
EventBusService,
|
||||
GiftCardService,
|
||||
} from "@medusajs/medusa"
|
||||
|
||||
type InjectedDependencies = {
|
||||
eventBusService: EventBusService
|
||||
giftCardService: GiftCardService
|
||||
}
|
||||
|
||||
class GiftCardSubscriber {
|
||||
giftCardService: GiftCardService
|
||||
|
||||
constructor({
|
||||
eventBusService,
|
||||
giftCardService,
|
||||
}: InjectedDependencies) {
|
||||
this.giftCardService = giftCardService
|
||||
eventBusService.subscribe(
|
||||
"gift_card.created", this.handleGiftCard)
|
||||
}
|
||||
|
||||
handleGiftCard = async (data) => {
|
||||
const giftCard = await this.giftCardService.retrieve(
|
||||
data.id
|
||||
)
|
||||
// TODO send customer the gift card code
|
||||
}
|
||||
}
|
||||
|
||||
export default GiftCardSubscriber
|
||||
```
|
||||
|
||||
When using this method, you’ll have to handle the logic of sending the code to the customer inside the handler function, which in this case is `handleGiftCard`.
|
||||
|
||||
The `handleGiftCard` event receives a `data` object as a parameter. This object holds the `id` property which is the ID of the gift card. You can retrieve the full gift card object using the [GiftCardService](../../../references/services/classes/GiftCardService.md)
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
description: 'Learn what gift cards are and how they work in the Medusa backend. Learn about the relations between Gift Cards and other entities.'
|
||||
---
|
||||
|
||||
# Gift Cards
|
||||
|
||||
In this document, you’ll learn about Gift Cards and how they work in Medusa.
|
||||
|
||||
## Introduction
|
||||
|
||||
Gift cards are products that customers can purchase and redeem in their future orders. Gift cards can have different amounts or denominations that a customer can choose from.
|
||||
|
||||
When a customer purchases a gift card, they should receive the code for the gift card by email or other type of notification. Then, they can use the code in their future purchases.
|
||||
|
||||
---
|
||||
|
||||
## Gift Cards as Products
|
||||
|
||||
Before a gift card is purchased, it’s essentially a `Product` entity. A store can have only one gift card with unlimited denominations.
|
||||
|
||||
The gift card product has an attribute `is_giftcard` set to `true`. Its `options` property includes only one option, which is Denomination. The different denomination values are stored as `variants`.
|
||||
|
||||
Once the customer purchases a gift card product, it is transformed into a usable gift card represented by the [GiftCard entity](#giftcard-entity-overview).
|
||||
|
||||
---
|
||||
|
||||
## Custom Gift Cards
|
||||
|
||||
Aside from the gift card product, merchants can create usable gift cards and send directly to customers. These can be used as a reward sent to the customer or another form of discount.
|
||||
|
||||
As custom gift cards can be used once they’re created, they’re also represented by the [GiftCard entity](#giftcard-entity-overview).
|
||||
|
||||
---
|
||||
|
||||
## GiftCard Entity Overview
|
||||
|
||||
Some of the [GiftCard](../../references/entities/classes/GiftCard.md) entity’s attributes are:
|
||||
|
||||
- `code`: a unique string of random characters. This is the code that the customer can use during their checkout to redeem the gift card.
|
||||
- `value`: The amount of the gift card. This is the amount the customer purchased, or was gifted in the case of custom gift cards.
|
||||
- `balance`: The remaining amount of the gift card. If the customer uses the gift card on an order, and the order’s total does not exceed the amount available in the gift card, the remaining balance would be stored in this attribute. When the gift card is first created, `balance` and `value` have the same value.
|
||||
- `is_disabled`: A boolean value indicating whether a gift card is disabled or not.
|
||||
- `ends_at`: The expiry date and time of the gift card.
|
||||
- `tax_rate`: The tax rate applied when calculating the totals of an order. The tax rate’s value is determined based on the following conditions:
|
||||
- If the value of `region.gift_cards_taxable` is `false`, the `tax_rate` is `null`;
|
||||
- Otherwise, if the merchant or admin user has manually set the value of the tax rate, it is applied;
|
||||
- Otherwise, if the region has a tax rate, it’s applied on the gift card. If not, the value of the tax rate is `null`.
|
||||
|
||||
---
|
||||
|
||||
## Relations to Other Entities
|
||||
|
||||
### Region
|
||||
|
||||
A gift card must belong to a region. When a customer purchases the gift card, the region they use to purchase the order is associated with the gift card.
|
||||
|
||||
For custom gift cards, the merchant specifies the region manually.
|
||||
|
||||
The ID of the region is stored in the attribute `region_id`. You can access the region by expanding the `region` relation and accessing `gift_card.region`.
|
||||
|
||||
### Order
|
||||
|
||||
If the gift card was created because the customer purchased it, it is associated with the placed order.
|
||||
|
||||
The ID of the order is stored in the attribute `order_id`. You can access the order by expanding the `order` relation and accessing `gift_card.order`.
|
||||
|
||||
You can also access the gift cards used in an order by expanding the `gift_cards` relation on the order and accessing `order.gift_cards`.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Manage gift cards using admin APIs](./admin/manage-gift-cards.mdx)
|
||||
- [Use gift cards in the storefront](./storefront/use-gift-cards.mdx)
|
||||
- [Send the customer a gift card](./backend/send-gift-card-to-customer.md)
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
description: "Gift cards are prepaid codes that can be purchased and used during checkout as an alternative to payment methods or to receive a discount. Learn about the available features and guides."
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import DocCard from '@theme/DocCard';
|
||||
import Icons from '@theme/Icon';
|
||||
|
||||
# Gift Cards
|
||||
|
||||
Gift cards are prepaid codes that can be purchased and used during checkout as an alternative to payment methods or to receive a discount. This overview introduces the available features related to gift cards.
|
||||
|
||||
:::note
|
||||
|
||||
Not a developer? Check out the [Gift Cards user guide](../../user-guide/gift-cards/index.md).
|
||||
|
||||
:::
|
||||
|
||||
## Features
|
||||
|
||||
### Gift Card Management
|
||||
|
||||
Admins can manage their main gift card with unlimited denominations.
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/gift-cards/admin/manage-gift-cards',
|
||||
label: 'Admin: Manage Gift Cards',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to manage gift cards using Admin APIs.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/user-guide/gift-cards/manage',
|
||||
label: 'User Guide: Manage Discounts',
|
||||
customProps: {
|
||||
icon: Icons['users-solid'],
|
||||
description: 'Learn how to manage gift cards using Medusa Admin.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
### Gift Card Purchasing
|
||||
|
||||
Customers can view the gift card and purchase it on the storefront. Customers can also use the gift card during checkout to deduct the gift card’s balance from the checkout total.
|
||||
|
||||
Developers can implement custom logic to send the gift card to the customer. They can alternatively implement a Shipping Profile that specifically handles the fulfillment of gift cards.
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/gift-cards/backend/send-gift-card-to-customer',
|
||||
label: 'Backend: Send Gift Card Code',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to use send a gift card code to a customer after their purchase.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/gift-cards/storefront/use-gift-cards',
|
||||
label: 'Storefront: Use Gift Cards',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to show gift cards to customers and allow them to redeem them.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
### Custom Gift Cards
|
||||
|
||||
Admins can create custom gift cards that are sent to specific customers. These customers can then use the gift card during checkout, the same way they would if they purchased one.
|
||||
|
||||
<DocCardList colSize={4} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/user-guide/gift-cards/custom',
|
||||
label: 'User Guide: Custom Gift Cards',
|
||||
customProps: {
|
||||
icon: Icons['users-solid'],
|
||||
description: 'Learn how to manage custom gift cards using Medusa Admin.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/gift-cards/admin/manage-gift-cards#manage-custom-gift-cards',
|
||||
label: 'Admin: Manage Custom Gift Cards',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to manage custom gift cards using Admin APIs.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/gift-cards/backend/send-gift-card-to-customer',
|
||||
label: 'Backend: Send Gift Card Code',
|
||||
customProps: {
|
||||
icon: Icons['academic-cap-solid'],
|
||||
description: 'Learn how to use send a custom gift card code to a customer.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
|
||||
---
|
||||
|
||||
## Understand the Architecture
|
||||
|
||||
Learn how gift card related entities and concepts are built, their relation to other modules, and more.
|
||||
|
||||
<DocCard item={{
|
||||
type: 'link',
|
||||
href: '/modules/gift-cards',
|
||||
label: 'Architecture: Gift Card',
|
||||
customProps: {
|
||||
icon: Icons['circle-stack-solid'],
|
||||
description: 'Learn about the Gift Card architecture.'
|
||||
}
|
||||
}}
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## Related Modules
|
||||
|
||||
Discover Gift Card's relation to other modules in Medusa
|
||||
|
||||
<DocCardList colSize={6} items={[
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/products/overview',
|
||||
label: 'Product',
|
||||
customProps: {
|
||||
icon: Icons['tag-solid'],
|
||||
description: 'A store’s main gift card is essentially a Product.'
|
||||
}
|
||||
},
|
||||
{
|
||||
type: 'link',
|
||||
href: '/modules/carts-and-checkout/overview',
|
||||
label: 'Cart and Checkout',
|
||||
customProps: {
|
||||
icon: Icons['shopping-cart-solid'],
|
||||
description: 'Gift Cards can be used during checkout.'
|
||||
}
|
||||
},
|
||||
]} />
|
||||
@@ -0,0 +1,323 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user