From f14ab4e64701e2a41592bd7f1e6ef3126eb4a77b Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 18 Apr 2023 13:58:02 +0300 Subject: [PATCH] docs: fix details about gift cards (#3869) --- .../gift-cards/admin/manage-gift-cards.mdx | 30 +++++++++++-------- docs/content/modules/gift-cards/gift-cards.md | 2 +- .../gift-cards/storefront/use-gift-cards.mdx | 21 +++++++------ 3 files changed, 28 insertions(+), 25 deletions(-) diff --git a/docs/content/modules/gift-cards/admin/manage-gift-cards.mdx b/docs/content/modules/gift-cards/admin/manage-gift-cards.mdx index 655913cdee..db64d542c2 100644 --- a/docs/content/modules/gift-cards/admin/manage-gift-cards.mdx +++ b/docs/content/modules/gift-cards/admin/manage-gift-cards.mdx @@ -24,7 +24,7 @@ Using the gift cards’ admin APIs, you can manage gift cards including listing, You want to add or use the following admin functionalities: -- Manage the gift card product including retrieving, adding, updating, and deleting it. +- Manage gift card products including retrieving, adding, updating, and deleting them. - Managing custom gift cards including retrieving, adding, updating and deleting them. --- @@ -57,13 +57,13 @@ 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 product. There can only be one gift card product in a store. The gift card can have unlimited denominations. +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 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: +You can retrieve the gift card products by sending a request to the [List Products](/api/admin/#tag/Product/operation/GetProducts) endpoint, but filtering the products with the `is_giftcard` flag: @@ -74,10 +74,9 @@ medusa.admin.products.list({ }) .then(({ products, limit, offset, count }) => { if (products.length) { - // gift card product exists - const giftcard = products[0] + // gift card products exist } else { - // no gift card product is created + // no gift card products are created } }) ``` @@ -129,10 +128,9 @@ fetch(`/admin/products?is_giftcard=true`, { .then((response) => response.json()) .then(({ products, limit, offset, count }) => { if (products.length) { - // gift card product exists - const giftcard = products[0] + // gift card products exist } else { - // no gift card product is created + // no gift card products are created } }) ``` @@ -148,13 +146,13 @@ curl -L -X GET '/admin/products?is_giftcard=true' \ -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 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 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](/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: +You can create a gift card product by sending a request to the [Create a Product](/api/admin/#tag/Product/operation/PostProducts) endpoint: @@ -345,6 +343,12 @@ You can pass other body parameters to change the handle, add images, and more. C 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. @@ -428,7 +432,7 @@ 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: +You can delete a gift card product by sending a request to the [Delete a Product](/api/admin/#tag/Product/operation/DeleteProductsProduct) endpoint: @@ -567,7 +571,7 @@ curl -L -X GET '/admin/gift-cards' \ -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 doesn't 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. diff --git a/docs/content/modules/gift-cards/gift-cards.md b/docs/content/modules/gift-cards/gift-cards.md index 205af0add5..a51d5c231e 100644 --- a/docs/content/modules/gift-cards/gift-cards.md +++ b/docs/content/modules/gift-cards/gift-cards.md @@ -16,7 +16,7 @@ When a customer purchases a gift card, they should receive the code for the gift ## 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. +Before a gift card is purchased, it’s essentially a `Product` entity. Each gift card can have 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`. diff --git a/docs/content/modules/gift-cards/storefront/use-gift-cards.mdx b/docs/content/modules/gift-cards/storefront/use-gift-cards.mdx index b634aa690b..c03cc95daa 100644 --- a/docs/content/modules/gift-cards/storefront/use-gift-cards.mdx +++ b/docs/content/modules/gift-cards/storefront/use-gift-cards.mdx @@ -18,7 +18,7 @@ Customers can view and purchase gift card products. Then, customers can redeem t You want to implement the following features in a storefront: -- Show the gift card product to the customer. +- Show gift card products to the customer. - View details of a gift card by its code. - Redeem a gift card during checkout. @@ -69,10 +69,10 @@ medusa.products.list({ }) .then(({ products, limit, offset, count }) => { if (products.length) { - // gift card product exists - const giftcard = products[0] + // gift card products exist + } else { - // no gift card product is created + // no gift card products are created } }) ``` @@ -84,7 +84,7 @@ medusa.products.list({ import { Product } from "@medusajs/medusa" import { useProducts } from "medusa-react" -const GiftCard = () => { +const GiftCards = () => { const { products, isLoading } = useProducts({ is_giftcard: true, }) @@ -106,7 +106,7 @@ const GiftCard = () => { ) } -export default GiftCard +export default GiftCards ``` @@ -119,10 +119,9 @@ fetch(`/store/products?is_giftcard=true`, { .then((response) => response.json()) .then(({ products, limit, offset, count }) => { if (products.length) { - // gift card product exists - const giftcard = products[0] + // gift card products exist } else { - // no gift card product is created + // no gift card products are created } }) ``` @@ -132,9 +131,9 @@ fetch(`/store/products?is_giftcard=true`, { 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) +You can use the `is_giftcard` query parameter to retrieve only the gift card products by setting its value 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). +The request returns the `products` array in the response, which holds the gift cards in it, if they're available. It also returns [pagination fields](/api/store/#section/Pagination). ### Show Gift Card’s Denominations