diff --git a/docs/content/modules/orders/overview.mdx b/docs/content/modules/orders/overview.mdx index efaf32e12f..3c5e5d51f0 100644 --- a/docs/content/modules/orders/overview.mdx +++ b/docs/content/modules/orders/overview.mdx @@ -74,12 +74,11 @@ Customers can view their previous orders. }, { type: 'link', - href: '#', - label: 'Storefront: Manage Customer Orders', + href: '/modules/orders/storefront/retrieve-order-details', + label: 'Storefront: Retrieve Order Details', customProps: { icon: Icons['academic-cap-solid'], - description: 'Learn how to manage orders as a customer.', - isSoon: true, + description: "Learn the different ways to retrieve an order's details", } }, ]} /> diff --git a/docs/content/modules/orders/storefront/handle-order-edits.mdx b/docs/content/modules/orders/storefront/handle-order-edits.mdx index 13c5cf7733..a2af816489 100644 --- a/docs/content/modules/orders/storefront/handle-order-edits.mdx +++ b/docs/content/modules/orders/storefront/handle-order-edits.mdx @@ -86,7 +86,7 @@ medusa.orderEdits.retrieve(orderEditId) -```ts +```tsx import { useOrderEdit } from "medusa-react" const OrderEdit = () => { @@ -217,7 +217,7 @@ medusa.paymentCollections.managePaymentSession(paymentCollectionId, { -```ts +```tsx import { useManagePaymentSession } from "medusa-react" const OrderEditPayment = () => { @@ -287,7 +287,7 @@ medusa -```ts +```tsx import { useAuthorizePaymentSession } from "medusa-react" const OrderEditPayment = () => { @@ -350,7 +350,7 @@ medusa.orderEdits.complete(orderEditId) -```ts +```tsx import { useCompleteOrderEdit } from "medusa-react" const OrderEdit = () => { @@ -419,7 +419,7 @@ medusa.orderEdits.decline(orderEditId, { -```ts +```tsx import { useDeclineOrderEdit } from "medusa-react" const OrderEdit = () => { diff --git a/docs/content/modules/orders/storefront/retrieve-order-details.mdx b/docs/content/modules/orders/storefront/retrieve-order-details.mdx new file mode 100644 index 0000000000..4282986944 --- /dev/null +++ b/docs/content/modules/orders/storefront/retrieve-order-details.mdx @@ -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 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 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.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#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](/api/store#tag/Orders/operation/GetOrdersOrder): + + + + +```ts +medusa.orders.retrieve(orderId) +.then(({ order }) => { + console.log(order.id) +}) +``` + + + + +```tsx +import { useOrder } from "medusa-react" + +const Order = () => { + const { + order, + isLoading, + } = useOrder(orderId) + + return ( +
+ {isLoading && Loading...} + {order && {order.display_id}} + +
+ ) +} + +export default Order +``` + + + + +```ts +fetch(`/store/orders/${orderId}`, { + credentials: "include", +}) +.then((response) => response.json()) +.then(({ order }) => { + console.log(order.id) +}) +``` + + + + +This endpoint requires the order’s ID to be passed as a path parameter. You can utilize the [expand](/api/store#section/Expanding-Fields) and [fields](/api/store#section/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](/api/store#tag/Orders/operation/GetOrders): + + + + +```ts +medusa.orders.lookupOrder({ + display_id: 1, + email: "user@example.com", +}) +.then(({ order }) => { + console.log(order.id) +}) +``` + + + + +```tsx +import { useOrders } from "medusa-react" + +const Order = () => { + const { + order, + isLoading, + } = useOrders(orderId) + + return ( +
+ {isLoading && Loading...} + {order && {order.display_id}} + +
+ ) +} + +export default Order +``` + + + + + + +```ts +fetch(`/store/orders?display_id=1&email=user@example.com`, { + credentials: "include", +}) +.then((response) => response.json()) +.then(({ order }) => { + console.log(order.id) +}) +``` + + + + +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](/api/store#tag/Orders/operation/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](/api/store#tag/Orders/operation/GetOrdersOrderCartId): + + + + +```ts +medusa.orders.retrieveByCartId(cartId) +.then(({ order }) => { + console.log(order.id) +}) +``` + + + + +```tsx +import { useCartOrder } from "medusa-react" + +const Order = () => { + const { + order, + isLoading, + } = useCartOrder(cartId) + + return ( +
+ {isLoading && Loading...} + {order && {order.display_id}} + +
+ ) +} + +export default Order +``` + + + + +```ts +fetch(`/store/orders/cart/${cartId}`, { + credentials: "include", +}) +.then((response) => response.json()) +.then(({ order }) => { + console.log(order.id) +}) +``` + + + + +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) diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index ab18317737..5b588352a9 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -794,12 +794,9 @@ module.exports = { label: "Admin: Manage Draft Orders", }, { - type: "link", - href: "#", - label: "Storefront: Manage Customer Orders", - customProps: { - sidebar_is_soon: true, - }, + type: "doc", + id: "modules/orders/storefront/retrieve-order-details", + label: "Storefront: Retrieve Order Details", }, { type: "link",