api-ref: custom API reference (#4770)
* initialized next.js project * finished markdown sections * added operation schema component * change page metadata * eslint fixes * fixes related to deployment * added response schema * resolve max stack issue * support for different property types * added support for property types * added loading for components * added more loading * type fixes * added oneOf type * removed console * fix replace with push * refactored everything * use static content for description * fixes and improvements * added code examples section * fix path name * optimizations * fixed tag navigation * add support for admin and store references * general enhancements * optimizations and fixes * fixes and enhancements * added search bar * loading enhancements * added loading * added code blocks * added margin top * add empty response text * fixed oneOf parameters * added path and query parameters * general fixes * added base path env variable * small fix for arrays * enhancements * design enhancements * general enhancements * fix isRequired * added enum values * enhancements * general fixes * general fixes * changed oas generation script * additions to the introduction section * added copy button for code + other enhancements * fix response code block * fix metadata * formatted store introduction * move sidebar logic to Tags component * added test env variables * fix code block bug * added loading animation * added expand param + loading * enhance operation loading * made responsive + improvements * added loading provider * fixed loading * adjustments for small devices * added sidebar label for endpoints * added feedback component * fixed analytics * general fixes * listen to scroll for other headings * added sample env file * update api ref files + support new fields * fix for external docs link * added new sections * fix last item in sidebar not showing * move docs content to www/docs * change redirect url * revert change * resolve build errors * configure rewrites * changed to environment variable url * revert changing environment variable name * add environment variable for API path * fix links * fix tailwind settings * remove vercel file * reconfigured api route * move api page under api * fix page metadata * fix external link in navigation bar * update api spec * updated api specs * fixed google lint error * add max-height on request samples * add padding before loading * fix for one of name * fix undefined types * general fixes * remove response schema example * redesigned navigation bar * redesigned sidebar * fixed up paddings * added feedback component + report issue * fixed up typography, padding, and general styling * redesigned code blocks * optimization * added error timeout * fixes * added indexing with algolia + fixes * fix errors with algolia script * redesign operation sections * fix heading scroll * design fixes * fix padding * fix padding + scroll issues * fix scroll issues * improve scroll performance * fixes for safari * optimization and fixes * fixes to docs + details animation * padding fixes for code block * added tab animation * fixed incorrect link * added selection styling * fix lint errors * redesigned details component * added detailed feedback form * api reference fixes * fix tabs * upgrade + fixes * updated documentation links * optimizations to sidebar items * fix spacing in sidebar item * optimizations and fixes * fix endpoint path styling * remove margin * final fixes * change margin on small devices * generated OAS * fixes for mobile * added feedback modal * optimize dark mode button * fixed color mode useeffect * minimize dom size * use new style system * radius and spacing design system * design fixes * fix eslint errors * added meta files * change cron schedule * fix docusaurus configurations * added operating system to feedback data * change content directory name * fixes to contribution guidelines * revert renaming content * added api-reference to documentation workflow * fixes for search * added dark mode + fixes * oas fixes * handle bugs * added code examples for clients * changed tooltip text * change authentication to card * change page title based on selected section * redesigned mobile navbar * fix icon colors * fix key colors * fix medusa-js installation command * change external regex in algolia * change changeset * fix padding on mobile * fix hydration error * update depedencies
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,234 @@
|
||||
---
|
||||
description: "Learn how to implement a create return flow in the storefront."
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Create a Return in the Storefront
|
||||
|
||||
In this document, you’ll learn how to implement a create return flow in the storefront.
|
||||
|
||||
## Overview
|
||||
|
||||
Customers may need to return items they received from an order they placed for different reasons, such as ordering an incorrect size of the item.
|
||||
|
||||
The Medusa backend allows automating the process of returning an item by providing the necessary mechanism that allows customers to create the return request themselves. This guide illustrates how you can implement that mechanism in your storefront.
|
||||
|
||||
The process of creating a return is as follows:
|
||||
|
||||
- Ask the customer to select the items they want to return. You can also allow customers to select the return shipping option to use to return the item.
|
||||
- Create the return in the Medusa backend.
|
||||
|
||||
:::note
|
||||
|
||||
Refunding the customer is handled by admins. You can learn how to implement or use this functionality in the [Manage Returns guide](../admin/manage-returns.mdx).
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Components
|
||||
|
||||
It's assumed that you already have a Medusa backend installed and set up. If not, you can follow our [quickstart guide](../../../development/backend/install.mdx) to get started.
|
||||
|
||||
It's 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 Template](../../../starters/nextjs-medusa-starter.mdx).
|
||||
|
||||
### JS Client
|
||||
|
||||
This guide includes code snippets to send requests to your Medusa backend 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).
|
||||
|
||||
### 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.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#usage).
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Collecting Return Details
|
||||
|
||||
When a customer wants to create a return, they must choose the items they want to return. To display the items in the order, you can retrieve the order as explained in [this guide](./retrieve-order-details.mdx). You can then display the items in an order using `order.items`, which is an array of items.
|
||||
|
||||
### Showing Return Shipping Options
|
||||
|
||||
You can optionally allow customers to choose a return shipping option that they’ll use to return the items. To show the customers the available return shipping options, send a request to the Get [Shipping Options endpoint](https://docs.medusajs.com/api/store#shipping-options_getshippingoptions):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.shippingOptions.list({
|
||||
is_return: "true",
|
||||
})
|
||||
.then(({ shipping_options }) => {
|
||||
console.log(shipping_options.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useShippingOptions } from "medusa-react"
|
||||
|
||||
const ReturnShippingOptions = () => {
|
||||
const {
|
||||
shipping_options,
|
||||
isLoading,
|
||||
} = useShippingOptions({
|
||||
is_return: "true",
|
||||
})
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{shipping_options?.length &&
|
||||
shipping_options?.length > 0 && (
|
||||
<ul>
|
||||
{shipping_options?.map((shipping_option) => (
|
||||
<li key={shipping_option.id}>
|
||||
{shipping_option.id}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default ReturnShippingOptions
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/shipping-options?is_return=true`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ shipping_options }) => {
|
||||
console.log(shipping_options.length)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint allows you to pass the `is_return` query parameter to indicate whether the shipping options should be return shipping options. You can learn about other available filters in the [API reference](https://docs.medusajs.com/api/store#shipping-options_getshippingoptions).
|
||||
|
||||
The request returns an array of shipping option objects.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create Return
|
||||
|
||||
You can create the return by sending a request to the [Create Return endpoint](https://docs.medusajs.com/api/store#returns_postreturns):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.returns.create({
|
||||
order_id,
|
||||
items: [
|
||||
{
|
||||
item_id,
|
||||
quantity: 1,
|
||||
},
|
||||
],
|
||||
return_shipping: {
|
||||
option_id,
|
||||
},
|
||||
})
|
||||
.then((data) => {
|
||||
console.log(data.return.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useCreateReturn } from "medusa-react"
|
||||
|
||||
const CreateReturn = () => {
|
||||
const createReturn = useCreateReturn()
|
||||
// ...
|
||||
|
||||
const handleCreate = () => {
|
||||
createReturn.mutate({
|
||||
order_id,
|
||||
items: [
|
||||
{
|
||||
item_id,
|
||||
quantity: 1,
|
||||
},
|
||||
],
|
||||
return_shipping: {
|
||||
option_id,
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default CreateReturn
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/returns`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
order_id,
|
||||
items: [
|
||||
{
|
||||
item_id,
|
||||
quantity: 1,
|
||||
},
|
||||
],
|
||||
return_shipping: {
|
||||
option_id,
|
||||
},
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then((data) => {
|
||||
console.log(data.return.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the following request body parameters:
|
||||
|
||||
- `order_id`: a string indicating the ID of the order to create the return for.
|
||||
- `items`: an array of objects, each object being an item from the order to return. Each object must have the following properties:
|
||||
- `item_id`: a string indicating the ID of the item in the order.
|
||||
- `quantity`: a number indicating the quantity to return.
|
||||
|
||||
You can optionally pass the `return_shipping` parameter, which is the return shipping option that the customer will use to return the item. It’s an object that has a required property `option_id`, which is a string indicating the ID of the return shipping option.
|
||||
|
||||
The request returns the created return as an object.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [How to manage returns as an admin](../admin/manage-returns.mdx)
|
||||
- [How to implement a create swap flow in a storefront](./create-swap.mdx)
|
||||
@@ -0,0 +1,252 @@
|
||||
---
|
||||
description: "Learn how to implement a create swap flow in a storefront."
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Create a Swap in the Storefront
|
||||
|
||||
In this document, you’ll learn how to implement a create swap flow in a storefront.
|
||||
|
||||
## Overview
|
||||
|
||||
Swaps allow customers to exchange items they ordered with new ones. This can be helpful if the customer ordered and received an item they didn’t like, if they ordered an incorrect size, or something similar.
|
||||
|
||||
The Medusa backend allows automating the process of exchanging an item with another by providing the necessary mechanism that allows customers to create the swap request themselves. This guide illustrates how you can implement that mechanism in your storefront.
|
||||
|
||||
The process of creating a swap is as follows:
|
||||
|
||||
- Ask the customer to select the items they want to replace, and which items they want to replace them with. You can also allow customers to select the return shipping option to use to return the item.
|
||||
- Create the swap in the Medusa backend.
|
||||
- Show a checkout flow using the swap’s cart. This allows the customer to provide their shipping details and authorize payment in a flow similar to that of placing an order.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Components
|
||||
|
||||
It's assumed that you already have a Medusa backend installed and set up. If not, you can follow our [quickstart guide](../../../development/backend/install.mdx) to get started.
|
||||
|
||||
It's 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 Template](../../../starters/nextjs-medusa-starter.mdx).
|
||||
|
||||
### JS Client
|
||||
|
||||
This guide includes code snippets to send requests to your Medusa backend 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).
|
||||
|
||||
### 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.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#usage).
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Collecting Swap Details
|
||||
|
||||
When a customer wants to create a swap, they must choose the items they want to return or replace and the items they want to receive instead.
|
||||
|
||||
To display the items in the order, you can retrieve the order as explained in [this guide](./retrieve-order-details.mdx). You can then display the items in an order using `order.items`, which is an array of items.
|
||||
|
||||
To allow the customers to choose other items to replace the items from the order, you can show them the available products in your store to choose from them. You can learn how to retrieve products in your storefront using [this guide](../../products/storefront/show-products.mdx).
|
||||
|
||||
You can optionally allow customers to choose a return shipping option that they’ll use to return the items. You can learn how to retrieve return shipping options in [this guide](./create-return.mdx#showing-return-shipping-options).
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create the Swap
|
||||
|
||||
After collecting the swap details in step 1, you can create a swap in the Medusa backend by sending a request to the [Create Swap endpoint](https://docs.medusajs.com/api/store#swaps_postswaps):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.swaps.create({
|
||||
order_id,
|
||||
return_items: [
|
||||
{
|
||||
item_id,
|
||||
quantity: 1,
|
||||
},
|
||||
],
|
||||
additional_items: [
|
||||
{
|
||||
variant_id,
|
||||
quantity: 1,
|
||||
},
|
||||
],
|
||||
return_shipping_option,
|
||||
})
|
||||
.then(({ swap }) => {
|
||||
console.log(swap.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useCreateSwap } from "medusa-react"
|
||||
|
||||
const CreateSwap = () => {
|
||||
const createSwap = useCreateSwap()
|
||||
// ...
|
||||
|
||||
const handleCreate = () => {
|
||||
createSwap.mutate({
|
||||
order_id,
|
||||
return_items: [
|
||||
{
|
||||
item_id,
|
||||
quantity: 1,
|
||||
},
|
||||
],
|
||||
additional_items: [
|
||||
{
|
||||
variant_id,
|
||||
quantity: 1,
|
||||
},
|
||||
],
|
||||
return_shipping_option,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default CreateSwap
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/swaps`, {
|
||||
credentials: "include",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
order_id,
|
||||
return_items: [
|
||||
{
|
||||
item_id,
|
||||
quantity: 1,
|
||||
},
|
||||
],
|
||||
additional_items: [
|
||||
{
|
||||
variant_id,
|
||||
quantity: 1,
|
||||
},
|
||||
],
|
||||
return_shipping_option,
|
||||
}),
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ swap }) => {
|
||||
console.log(swap.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the following request body parameters:
|
||||
|
||||
- `order_id`: a string indicating the ID of the order that this swap is created for.
|
||||
- `return_items`: an array of objects, each object being the item to return. Each object should have the following properties:
|
||||
- `item_id`: a string indicating the ID of the item in the order.
|
||||
- `quantity`: a number indicating the quantity to return.
|
||||
- `additional_items`: an array of objects, each object being the new item to receive. Each object should have the following properties:
|
||||
- `variant_id`: a string indicating the ID of the product variant.
|
||||
- `quantity`: a number indicating the quantity to add.
|
||||
|
||||
You can optionally pass the `return_shipping_option` body parameter, which is a string indicating the ID of the shipping option.
|
||||
|
||||
The request returns the swap as an object.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Complete Swap with Checkout Flow
|
||||
|
||||
The swap can be completed in the same flow as a checkout flow. Since a swap is associated with a cart, you can implement the checkout flow using the cart of the swap. You can access the cart of a swap in the swap object using `swap.cart`.
|
||||
|
||||
Since the Medusa backend knows the cart is associated with the swap, it will ensure that the flow is performed in the context of a swap. You can learn how to implement a checkout flow in your storefront using [this guide](../../carts-and-checkout/storefront/implement-checkout-flow.mdx).
|
||||
|
||||
:::note
|
||||
|
||||
When you complete the cart, the returned `type` field can be used to indicate the context of the checkout flow. In the case of a swap, the value of `type` will be `swap`.
|
||||
|
||||
:::
|
||||
|
||||
### Retrieve Swap by Cart ID
|
||||
|
||||
During your checkout flow, you might need to retrieve the swap using the cart’s ID. For example, if you want to display the swap’s details after the cart is successfully completed. You can do that using the [Get by Cart ID endpoint](https://docs.medusajs.com/api/store#swaps_getswapsswapcartid):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.swaps.retrieveByCartId(cartId)
|
||||
.then(({ swap }) => {
|
||||
console.log(swap.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useCartSwap } from "medusa-react"
|
||||
|
||||
const Swap = () => {
|
||||
const {
|
||||
swap,
|
||||
isLoading,
|
||||
} = useCartSwap(cartId)
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{swap && <span>{swap.id}</span>}
|
||||
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default Swap
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/swaps/${cartId}`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ swap }) => {
|
||||
console.log(swap.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the ID of the cart as a path parameter.
|
||||
|
||||
The request returns the swap as an object.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [How to implement a create return flow in a storefront](./create-return.mdx)
|
||||
- [How to retrieve order details in a storefront](./retrieve-order-details.mdx)
|
||||
@@ -0,0 +1,477 @@
|
||||
---
|
||||
description: 'Learn how to implement order-edit related features in the storefront using REST APIs. This includes showing the customer order-edit requests, authorizing additional payments, and confirming or declining order edits.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Handle an Order Edit in Storefront
|
||||
|
||||
In this document, you’ll learn how to allow a customer to confirm or decline an Order Edit.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
A merchant can request to edit an order to make changes to its items. The change can include removing an item, adding a new item, and changing the quantity of an item in the original order.
|
||||
|
||||
When the Order Edit is in the “request” state, it requires either a confirmation from the customer, or it can be force-confirmed by the merchant.
|
||||
|
||||
This guide focuses on how to use the Storefront APIs to implement the flow that allows a customer to either confirm or decline an Order Edit.
|
||||
|
||||
:::note
|
||||
|
||||
You can check out how to implement order editing using the Admin APIs in [this documentation](../admin/edit-order.mdx).
|
||||
|
||||
:::
|
||||
|
||||
### Scenarios
|
||||
|
||||
You want to implement the following functionalities in your storefront:
|
||||
|
||||
- List and show customers order-edit requests.
|
||||
- Confirm order edits and authorize any additional payment if necessary.
|
||||
- Decline order edits.
|
||||
|
||||
:::note
|
||||
|
||||
You can perform other functionalities related to order editing. To learn more, check out the API reference.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Components
|
||||
|
||||
It's assumed that you already have a Medusa backend installed and set up. If not, you can follow our [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 Template](../../../starters/nextjs-medusa-starter.mdx).
|
||||
|
||||
### JS Client
|
||||
|
||||
This guide includes code snippets to send requests to your Medusa backend 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).
|
||||
|
||||
### 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.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#usage).
|
||||
|
||||
### Previous Steps
|
||||
|
||||
You must have an existing order edit in the “request” state.
|
||||
|
||||
---
|
||||
|
||||
## Retrieve an Order Edit
|
||||
|
||||
You can retrieve a single order edit by its ID by sending a request to the [Get Order Edit](https://docs.medusajs.com/api/store#order-edits_getordereditsorderedit) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.orderEdits.retrieve(orderEditId)
|
||||
.then(({ order_edit }) => {
|
||||
console.log(order_edit.changes)
|
||||
// show changed items to the customer
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useOrderEdit } from "medusa-react"
|
||||
|
||||
const OrderEdit = () => {
|
||||
const { order_edit, isLoading } = useOrderEdit(orderEditId)
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default OrderEdit
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/order-edits/${orderEditId}`)
|
||||
.then((response) => response.json())
|
||||
.then(({ order_edit }) => {
|
||||
console.log(order_edit.changes)
|
||||
// show changed items to the customer
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
The request requires the order edit’s ID as a path parameter.
|
||||
|
||||
It returns the Order Edit as an object. Some of its important fields are:
|
||||
|
||||
- `order_id`: The ID of the order that this Order Edit belongs to.
|
||||
- `difference_due`: The amount to either be refunded or paid. If the amount is greater than 0, then the customer is required to pay an additional amount. If the amount is less than 0, then the merchant has to refund the difference to the customer.
|
||||
- `payment_collection_id`: The ID of the payment collection. This will be used to authorize additional payment if necessary.
|
||||
|
||||
:::note
|
||||
|
||||
You can learn more about what fields to expect in the [API reference](https://docs.medusajs.com/api/store#order-edits_getordereditsorderedit).
|
||||
|
||||
:::
|
||||
|
||||
### Show Changed Items
|
||||
|
||||
All data about changes to the original order’s items can be found in `order_edit.changes`. `changes` is an array of item changes. Each item change includes the following fields:
|
||||
|
||||
<!-- eslint-skip -->
|
||||
|
||||
```ts
|
||||
{
|
||||
type: string,
|
||||
line_item: LineItem | null,
|
||||
original_line_item: LineItem | null
|
||||
}
|
||||
```
|
||||
|
||||
`type` can be either:
|
||||
|
||||
- `item_add`: In this case, a new item is being added. `line_item` will be an item object and `original_line_item` will be `null`.
|
||||
- `item_update`: In this case, an item’s quantity in the original order is updated. `line_item` will be the updated item, and `original_line_item` will be the item in the original order. You can either just use `line_item` to show the new quantity, or show the customer a comparison between the old and new quantity using `original_line_item` as well.
|
||||
- `item_remove`: In this case, an item in the original order is removed. The `original_line_item` will be the item in the original order, and `line_item` will be `null`.
|
||||
|
||||
Here’s an example of how you can use this data to show the customer the requested edits to the order:
|
||||
|
||||
```tsx
|
||||
<ul>
|
||||
{orderEdit.changes.map((itemChange) => (
|
||||
<li key={itemChange.id}>
|
||||
<strong>
|
||||
{
|
||||
itemChange.line_item ?
|
||||
itemChange.line_item.title :
|
||||
itemChange.original_line_item.title
|
||||
}
|
||||
</strong>
|
||||
{itemChange.type === "added" && <span>New Item</span>}
|
||||
{itemChange.type === "removed" && (
|
||||
<span>Removed Item</span>
|
||||
)}
|
||||
{itemChange.type === "edited" &&
|
||||
<span>
|
||||
Edited Item
|
||||
Old Quantity: {itemChange.original_line_item.quantity}
|
||||
New Quantity: {itemChange.line_item.quantity}
|
||||
</span>}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Handle Payment
|
||||
|
||||
After viewing the changes in the order edit, the customer can choose to confirm or decline the order edit.
|
||||
|
||||
In case the customer wants to confirm the order edit, you must check whether a refund or an additional payment is required. You can check that by checking the value of `difference_due`.
|
||||
|
||||
### Refund Amount
|
||||
|
||||
If `difference_due` is less than 0, then the amount will be refunded to the customer by the merchant from the Medusa admin. No additional actions are required here before [completing the order edit](#complete-the-order-edit).
|
||||
|
||||
### Make Additional Payments
|
||||
|
||||
:::note
|
||||
|
||||
This section explains how to authorize the payment using one payment processor and payment session. However, payment collections allow customers to pay in installments or with more than one provider. You can learn more about how to do that using the [batch endpoints of the Payment APIs](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionssessionsbatchauthorize)
|
||||
|
||||
:::
|
||||
|
||||
If `difference_due` is greater than 0, then additional payment from the customer is required. In this case, you must implement these steps to allow the customer to authorize the payment:
|
||||
|
||||
1. Show the customer the available payment processors. These can be retrieved from the details of [the region of the order](https://docs.medusajs.com/api/store#regions_getregions).
|
||||
2. When the customer selects the payment processor, initialize the payment session of that provider in the payment collection. You can do that by sending a request to the [Manage Payment Sessions](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionspaymentcollectionsessionsbatch) endpoint, passing it the payment collection’s ID as a path parameter, and the payment processor's ID as a request body parameter:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
medusa.paymentCollections.managePaymentSession(paymentCollectionId, {
|
||||
provider_id,
|
||||
})
|
||||
.then(({ payment_collection }) => {
|
||||
console.log(payment_collection.payment_sessions)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useManagePaymentSession } from "medusa-react"
|
||||
|
||||
const OrderEditPayment = () => {
|
||||
const managePaymentSession = useManagePaymentSession(
|
||||
paymentCollectionId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleAdditionalPayment = (provider_id: string) => {
|
||||
managePaymentSession.mutate({
|
||||
provider_id,
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default OrderEditPayment
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/store/payment-collections/${paymentCollectionId}/sessions`,
|
||||
{
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
provider_id,
|
||||
}),
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ payment_collection }) => {
|
||||
console.log(payment_collection.payment_sessions)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
1. Show the customer the payment details form based on the payment session’s provider. For example, if the provider ID of a payment session is `stripe`, you must show Stripe’s card component to enter the customer’s card details.
|
||||
2. Authorize the payment using the payment processor. The [Authorize Payment Session](https://docs.medusajs.com/api/store#payment-collections_postpaymentcollectionssessionssessionauthorize) endpoint accepts the payment collection’s ID and the ID of the payment session as path parameters:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa
|
||||
.paymentCollection
|
||||
.authorizePaymentSession(
|
||||
paymentCollectionId,
|
||||
paymentSessionId
|
||||
)
|
||||
.then(({ payment_session }) => {
|
||||
console.log(payment_session.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useAuthorizePaymentSession } from "medusa-react"
|
||||
|
||||
const OrderEditPayment = () => {
|
||||
const authorizePaymentSession = useAuthorizePaymentSession(
|
||||
paymentCollectionId
|
||||
)
|
||||
// ...
|
||||
|
||||
const handleAuthorizePayment = (paymentSessionId: string) => {
|
||||
authorizePaymentSession.mutate(paymentSessionId)
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default OrderEditPayment
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/store/payment-collection/${paymentCollectionId}` +
|
||||
`/sessions/${paymentSessionId}/authorize`,
|
||||
{
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ payment_session }) => {
|
||||
console.log(payment_session.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
After performing the above steps, you can [complete the Order Edit](#complete-the-order-edit).
|
||||
|
||||
---
|
||||
|
||||
## Complete the Order Edit
|
||||
|
||||
To confirm and complete the order edit, send a request to the [Complete Order Edit](https://docs.medusajs.com/api/store#order-edits_postordereditsordereditcomplete) endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.orderEdits.complete(orderEditId)
|
||||
.then(({ order_edit }) => {
|
||||
console.log(order_edit.confirmed_at)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useCompleteOrderEdit } from "medusa-react"
|
||||
|
||||
const OrderEdit = () => {
|
||||
const completeOrderEdit = useCompleteOrderEdit(orderEditId)
|
||||
// ...
|
||||
|
||||
const handleCompleteOrderEdit = () => {
|
||||
completeOrderEdit.mutate()
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default OrderEdit
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/order-edits/${orderEditId}/complete`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ order_edit }) => {
|
||||
console.log(order_edit.confirmed_at)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts the order edit’s ID as a path parameter.
|
||||
|
||||
It returns the full Order Edit object. You can find properties related to the order confirmation, such as `order_edit.confirmed_at`.
|
||||
|
||||
After completing the order edit, the changes proposed in the Order Edit are reflected in the original order.
|
||||
|
||||
:::info
|
||||
|
||||
If the payment isn’t authorized first, the order edit completion will fail.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Decline an Order Edit
|
||||
|
||||
If the customer wants to decline the Order Edit, you can do that by sending a request to the Decline Order Edit endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.orderEdits.decline(orderEditId, {
|
||||
decline_reason: "I am not satisfied",
|
||||
})
|
||||
.then(({ order_edit }) => {
|
||||
console.log(order_edit.declined_at)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useDeclineOrderEdit } from "medusa-react"
|
||||
|
||||
const OrderEdit = () => {
|
||||
const declineOrderEdit = useDeclineOrderEdit(orderEditId)
|
||||
// ...
|
||||
|
||||
const handleDeclineOrderEdit = () => {
|
||||
declineOrderEdit.mutate({
|
||||
declined_reason: "I am not satisfied",
|
||||
})
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default OrderEdit
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(
|
||||
`<BACKEND_URL>/store/order-edits/${orderEditId}/decline`,
|
||||
{
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({
|
||||
decline_reason: "I am not satisfied",
|
||||
}),
|
||||
}
|
||||
)
|
||||
.then((response) => response.json())
|
||||
.then(({ order_edit }) => {
|
||||
console.log(order_edit.declined_at)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
The request requires passing the order edit’s ID as a path parameter.
|
||||
|
||||
In the request body parameters, you can optionally pass the `decline_reason` parameter. It’s a string that indicates to the merchant the reason the customer declined the order edit.
|
||||
|
||||
If the Order Edit is declined, the changes requested in the Order Edit aren't reflected on the original order and no refund or additional payments are required.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Edit an order using Admin APIs](../admin/edit-order.mdx)
|
||||
@@ -0,0 +1,210 @@
|
||||
---
|
||||
description: 'Learn how to implement the order-claim flow in the storefront. This includes allowing customers to claim their orders, and verify a claim to an order.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Implement Claim Order Flow in Storefront
|
||||
|
||||
In this document, you’ll learn how to implement the claim order flow in a storefront to allow customers to claim their orders.
|
||||
|
||||
:::note
|
||||
|
||||
This flow was added starting from Medusa v1.7. You can learn more about upgrading in the [upgrade guide](../../../upgrade-guides/medusa-core/1-7-0.md).
|
||||
|
||||
:::
|
||||
|
||||
## Flow Overview
|
||||
|
||||
When a guest customer places an order, their order is not associated with any customer. The order is only associated with an email that the guest customer provides during checkout.
|
||||
|
||||
This email must be an email that isn’t used with an existing account. It can, however, be used to create another order as a guest customer.
|
||||
|
||||
After this customer registers with a different email and logs in, they can claim their order by providing the order’s ID. An email will then be sent to the email address associated with the order.
|
||||
|
||||
The email should contain a link to a page in the storefront, and the link should have a token as a parameter. This token will be used for verification.
|
||||
|
||||
The customer must then click the link in the email they received. If the token is valid, the order will be associated with the customer.
|
||||
|
||||
|
||||
|
||||
### What You’ll Learn
|
||||
|
||||
In this document, you’ll learn how to implement two parts of this flow:
|
||||
|
||||
1. Allow customers to claim their orders.
|
||||
2. Verify a claim to an order.
|
||||
|
||||
---
|
||||
|
||||
## 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 Template](../../../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.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#usage).
|
||||
|
||||
### Handle Order Claim Request Event
|
||||
|
||||
When the customer requests to claim the order, an event will be triggered. You should subscribe to this event to send a confirmation email to the customer when the event is triggered.
|
||||
|
||||
You can learn how to implement this flow in [this documentation](../backend/handle-order-claim-event.md).
|
||||
|
||||
### Previous Steps
|
||||
|
||||
It is assumed you already have an order placed by a guest customer. You can refer to the [Cart](../../carts-and-checkout/storefront/implement-cart) and [Checkout](../../carts-and-checkout/storefront/implement-checkout-flow.mdx) implementation documentation to learn how to implement them in your storefront.
|
||||
|
||||
In addition, it is assumed you already have a logged-in customer before performing the steps in this document. You can refer to the [API reference](https://docs.medusajs.com/api/store#auth_postauth) for more details on that.
|
||||
|
||||
---
|
||||
|
||||
## Request to Claim an Order
|
||||
|
||||
When the customer wants to claim an order, they must supply its ID.
|
||||
|
||||
To allow the customer to claim an order, send a request to the Claim an Order endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.orders.requestCustomerOrders({
|
||||
order_ids: [
|
||||
order_id,
|
||||
],
|
||||
})
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
.catch(() => {
|
||||
// an error occurred
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/orders/batch/customer/token`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
body: JSON.stringify({
|
||||
order_ids: [
|
||||
order_id,
|
||||
],
|
||||
}),
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
})
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
.catch(() => {
|
||||
// display an error to the customer
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts as a body parameter the array `order_ids`. Each item in the array is the ID of an order that the customer wants to claim. You can pass more than one ID.
|
||||
|
||||
If the customer’s request has been processed successfully, the request returns a response with a `200` status code.
|
||||
|
||||
The customer at this point will receive an email with a link to verify their claim on the order.
|
||||
|
||||
---
|
||||
|
||||
## Manually Verify a Claim to an Order
|
||||
|
||||
The link in the email that the customer receives should be a page in your storefront that accepts a `token` query parameter.
|
||||
|
||||
Then, you send a request to the Verify Claim Order endpoint:
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.orders.confirmRequest({
|
||||
token,
|
||||
})
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
.catch(() => {
|
||||
// an error occurred
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useGrantOrderAccess } from "medusa-react"
|
||||
|
||||
const ClaimOrder = () => {
|
||||
const grantOrderAccess = useGrantOrderAccess()
|
||||
// ...
|
||||
|
||||
const handleVerifyOrderClaim = (token: string) => {
|
||||
grantOrderAccess.mutate(({
|
||||
token,
|
||||
}))
|
||||
}
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
export default ClaimOrder
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/orders/customer/confirm`, {
|
||||
method: "POST",
|
||||
credentials: "include",
|
||||
body: JSON.stringify({
|
||||
token,
|
||||
}),
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
})
|
||||
.then(() => {
|
||||
// successful
|
||||
})
|
||||
.catch(() => {
|
||||
// display an error to the customer
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This request accepts as a body parameter the string `token`. This would be the token passed as a parameter to your storefront page through the link in the email.
|
||||
|
||||
If the verification is successful, the order will now be associated with the customer and the customer will be able to see it among their orders.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Send a confirmation email to claim an order](../backend/handle-order-claim-event.md)
|
||||
@@ -0,0 +1,242 @@
|
||||
---
|
||||
description: "Learn the different ways you can retrieve and view a customer’s orders, whether they're a guest customer or logged-in."
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# How to Retrieve Order Details on the Storefront
|
||||
|
||||
In this document, you’ll learn the different ways you can retrieve and view a customer’s orders, whether they're a guest customer or logged-in.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Components
|
||||
|
||||
It's assumed that you already have a Medusa backend installed and set up. If not, you can follow our [quickstart guide](../../../development/backend/install.mdx) to get started.
|
||||
|
||||
It's 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 Template](../../../starters/nextjs-medusa-starter.mdx).
|
||||
|
||||
### JS Client
|
||||
|
||||
This guide includes code snippets to send requests to your Medusa backend 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).
|
||||
|
||||
### 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.mdx) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.mdx#usage).
|
||||
|
||||
---
|
||||
|
||||
## Retrieve Order by ID
|
||||
|
||||
Retrieving an order by its ID is useful for different scenarios, such as using an order details page. You can use this method for both logged in and guest customers.
|
||||
|
||||
You can retrieve an order by its ID using the [Get Order endpoint](https://docs.medusajs.com/api/store#orders_getordersorder):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.orders.retrieve(orderId)
|
||||
.then(({ order }) => {
|
||||
console.log(order.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useOrder } from "medusa-react"
|
||||
|
||||
const Order = () => {
|
||||
const {
|
||||
order,
|
||||
isLoading,
|
||||
} = useOrder(orderId)
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{order && <span>{order.display_id}</span>}
|
||||
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default Order
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/orders/${orderId}`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ order }) => {
|
||||
console.log(order.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the order’s ID to be passed as a path parameter. You can utilize the [expand](https://docs.medusajs.com/api/store#expanding-fields) and [fields](https://docs.medusajs.com/api/store#selecting-fields) query parameters to select parameters and relations to return.
|
||||
|
||||
The request returns the order as an object.
|
||||
|
||||
---
|
||||
|
||||
## Retrieve Order by Display ID
|
||||
|
||||
Display IDs allow you to show human-readable IDs to your customers. Retrieving an order by its display ID is useful in many situations, such as allowing customers to look up their orders with a search field. This method of retrieving an order can be used for both logged-in customers and guest customers.
|
||||
|
||||
You can retrieve an order by its display ID using the [Look Up Order endpoint](https://docs.medusajs.com/api/store#orders_getorders):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.orders.lookupOrder({
|
||||
display_id: 1,
|
||||
email: "user@example.com",
|
||||
})
|
||||
.then(({ order }) => {
|
||||
console.log(order.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useOrders } from "medusa-react"
|
||||
|
||||
const Order = () => {
|
||||
const {
|
||||
order,
|
||||
isLoading,
|
||||
} = useOrders(orderId)
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{order && <span>{order.display_id}</span>}
|
||||
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default Order
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/orders?display_id=1&email=user@example.com`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ order }) => {
|
||||
console.log(order.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires two query parameters:
|
||||
|
||||
- `display_id`: a string indicating display ID of the order. If you already have an order object, you can retrieve the display ID using `order.display_id`.
|
||||
- `email`: a string indicating the email associated with the order.
|
||||
|
||||
You can pass other query parameters to filter the orders even further, and the endpoint will return the first order that matches the filters. Learn more about available query parameters in the [API reference](https://docs.medusajs.com/api/store#orders_getorders).
|
||||
|
||||
The request returns the order as an object.
|
||||
|
||||
---
|
||||
|
||||
## Retrieve Order by Cart ID
|
||||
|
||||
In certain scenarios, you may need to retrieve an order’s details using the ID of the cart associated with the order. This can be useful when showing a success page after a cart is completed and an order is placed.
|
||||
|
||||
You can retrieve an order by the cart ID using the [Get by Cart ID endpoint](https://docs.medusajs.com/api/store#orders_getordersordercartid):
|
||||
|
||||
<Tabs groupId="request-type" isCodeTabs={true}>
|
||||
<TabItem value="client" label="Medusa JS Client" default>
|
||||
|
||||
```ts
|
||||
medusa.orders.retrieveByCartId(cartId)
|
||||
.then(({ order }) => {
|
||||
console.log(order.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="medusa-react" label="Medusa React">
|
||||
|
||||
```tsx
|
||||
import { useCartOrder } from "medusa-react"
|
||||
|
||||
const Order = () => {
|
||||
const {
|
||||
order,
|
||||
isLoading,
|
||||
} = useCartOrder(cartId)
|
||||
|
||||
return (
|
||||
<div>
|
||||
{isLoading && <span>Loading...</span>}
|
||||
{order && <span>{order.display_id}</span>}
|
||||
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default Order
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="fetch" label="Fetch API">
|
||||
|
||||
```ts
|
||||
fetch(`<BACKEND_URL>/store/orders/cart/${cartId}`, {
|
||||
credentials: "include",
|
||||
})
|
||||
.then((response) => response.json())
|
||||
.then(({ order }) => {
|
||||
console.log(order.id)
|
||||
})
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This endpoint requires the ID of the cart as a path parameter.
|
||||
|
||||
The request returns the order as an object.
|
||||
|
||||
---
|
||||
|
||||
## Retrieve a Customer’s Orders
|
||||
|
||||
When a customer is logged in, you can retrieve a list of their orders. This is typically useful to show a customer their orders in their profile. This method can only be used for logged-in customers.
|
||||
|
||||
You can learn how to retrieve a customer’s orders in the [How to Implement Customer Profiles](/modules/customers/storefront/implement-customer-profiles#retrieve-a-customers-orders) documentation.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [How to handle order edits in the storefront](./handle-order-edits.mdx)
|
||||
- [How to implement claim order flow in the storefront](./implement-claim-order.mdx)
|
||||
Reference in New Issue
Block a user