240 lines
7.8 KiB
Plaintext
240 lines
7.8 KiB
Plaintext
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 server installed and set up. If not, you can follow the [quickstart guide](../../quickstart/quick-start.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 either the [Next.js](../../starters/nextjs-medusa-starter.mdx) or [Gatsby](../../starters/gatsby-medusa-starter.mdx) storefronts.
|
||
|
||
### JS Client
|
||
|
||
This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client and JavaScript’s Fetch API.
|
||
|
||
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).
|
||
|
||
### 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](./how-to-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="fetch" label="Fetch API">
|
||
|
||
```ts
|
||
fetch(`<SERVER_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="fetch" label="Fetch API">
|
||
|
||
```ts
|
||
fetch(`<SERVER_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="fetch" label="Fetch API">
|
||
|
||
```ts
|
||
fetch(`<SERVER_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.
|
||
|
||
---
|
||
|
||
## See Also
|
||
|
||
- [Gift cards overview](../backend/gift-cards/index.md)
|
||
- [Manage gift cards using admin APIs](../admin/manage-gift-cards.mdx)
|
||
- [Send the customer a gift card](../ecommerce/send-gift-card-to-customer.md)
|
||
- Gift cards [store](/api/store/#tag/Gift-Card) and [admin](/api/admin/#tag/Gift-Card) APIs
|