asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: added manage claims documentation (#3944)

Browse Source 
* docs: added manage claims documentation

* remove sidebar item

* fixed link
This commit is contained in:
Shahed Nasser
2023-04-27 16:43:07 +03:00
committed by GitHub
parent 588abbe833
commit d38b3249f7
6 changed files with 676 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

663
docs/content/modules/orders/admin/manage-claims.mdx Normal file
View File

@@ -0,0 +1,663 @@
---
description: "Learn how to manage claims using the admin REST APIs. This guide includes how to view an order's claims, "
addHowToData: true
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# How to Manage Claims
In this document, you’ll learn how to manage claims using the admin REST APIs.
## Overview
Using Medusa’s claim admin REST APIs, you can manage claims and perform related admin functionalities.
### Scenario
You want to add or use the following admin functionalities:
- View an order’s claims
- Manage claims, including creating, updating, and canceling claims.
- Manage a claim’s fulfillment, including creating a fulfillment, creating a shipment, and canceling a fulfillment.
:::note
You can learn about managing returns part of a claim in the [Manage Returns documentation](./manage-returns.mdx).
:::
---
## Prerequisites
### Medusa Components
It is 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.
### 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).
---
## View Order’s Claims
To view an order’s claims, you can retrieve the order using the [Get Order endpoint](/api/admin#tag/Orders/operation/GetOrdersOrder) and access the order’s claims:
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.orders.retrieve(orderId)
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminOrder } from "medusa-react"
const Order = () => {
const {
order,
isLoading,
} = useAdminOrder(orderId)
return (
<div>
{isLoading && <span>Loading...</span>}
{order && (
<>
<span>{order.display_id}</span>
{order.claims?.length > 0 && (
<ul>
{order.claims.map((claim) => (
<li key={claim.id}>{claim.id}</li>
))}
</ul>
)}
</>
)}
</div>
)
}
export default Order
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```ts
fetch(`<BACKEND_URL>/admin/orders/${orderId}`, {
credentials: "include",
})
.then((response) => response.json())
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl -L -X GET '<BACKEND_URL>/admin/orders/<ORDER_ID>' \
-H 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
</Tabs>
This request requires the order’s ID as a path parameter.
The request returns the order as an object. In that object, you can access an array of claim objects using the property `claims` of the order object.
---
## Create Claim
You can create a claim by sending a request to the [Create Claim endpoint](/api/admin#tag/Orders/operation/PostOrdersOrderClaims):
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.orders.createClaim(orderId, {
type: "refund",
claim_items: [
{
item_id,
quantity: 1,
},
],
})
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminCreateClaim } from "medusa-react"
const CreateClaim = () => {
const createClaim = useAdminCreateClaim(orderId)
// ...
const handleCreate = () => {
createClaim.mutate({
type: "refund",
claim_items: [
{
item_id,
quantity: 1,
},
],
})
}
// ...
}
export default CreateClaim
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```ts
fetch(`<BACKEND_URL>/admin/orders/${orderId}/claims`, {
credentials: "include",
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
type: "refund",
claim_items: [
{
item_id,
quantity: 1,
},
],
}),
})
.then((response) => response.json())
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
"type": "refund",
"claim_items": [
{
"item_id": "<ITEM_ID>",
"quantity": 1
}
]
}'
```
</TabItem>
</Tabs>
This endpoint requires the order ID to be passed as a path parameter.
In the request body, the following parameters are required:
- `type`: a string indicating the type of claim to be created. Its value can either be `replace` or `refund`. If the type is `replace`, you can pass the `additional_items` parameter with an array of new items to send to the customer. If the type is `refund`, you can pass the `refund_amount` parameter if you want to specify a custom refund amount.
- `claim_items`: an array of objects, each object being the item in the order that the claim is being created for. In the object, you must pass the following properties:
- `item_id`: a string indicating the ID of the line item in the order.
- `quantity`: a number indicating the quantity of the claim.
There are other optional parameters that you can pass. You can also pass a return reason for each of the claim items. You can learn about the optional request body parameters in the [API reference](/api/admin#tag/Orders/operation/PostOrdersOrderClaims).
:::note
Learn how to manage return reasons in [this documentation](./manage-returns.mdx#manage-return-reasons).
:::
The request returns the updated order as an object. You can access the order’s claims using the `claims` property of the order object. The value of the `claims` property is an array of claim objects.
---
## Update a Claim
You can update a claim by sending a request to the [Update Claim endpoint](/api/admin#tag/Orders/operation/PostOrdersOrderClaimsClaim):
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.orders.updateClaim(orderId, claimId, {
no_notification: true,
})
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminUpdateClaim } from "medusa-react"
const UpdateClaim = () => {
const updateClaim = useAdminUpdateClaim(orderId)
// ...
const handleUpdate = () => {
updateClaim.mutate({
claim_id,
no_notification: true,
})
}
// ...
}
export default UpdateClaim
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
```ts
fetch(
`<BACKEND_URL>/admin/orders/${orderId}/claims/${claimId}`,
{
credentials: "include",
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
no_notification: true,
}),
}
)
.then((response) => response.json())
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
"no_notification": true
}'
```
</TabItem>
</Tabs>
This endpoint requires the ID of the order and the claim to be passed as path parameters.
In the request body, you can pass any of the claim’s fields that you want to update as parameters. In the example above, the `no_notification` field is updated.
The request returns the updated order as an object. You can access the order’s claims using the `claims` property of the order object. The value of the `claims` property is an array of claim objects.
---
## Manage a Claim’s Fulfillments
### View Claim’s Fulfillments
Fulfillments are available on a claim object under the `fulfillments` property, which is an array of fulfillment objects.
### Create Fulfillment
You can create a fulfillment for a claim by sending a request to the [Create Claim Fulfillment endpoint](/api/admin#tag/Orders/operation/PostOrdersOrderClaimsClaimFulfillments):
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.orders.fulfillClaim(orderId, claimId, {
})
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminFulfillClaim } from "medusa-react"
const FulfillClaim = () => {
const fulfillClaim = useAdminFulfillClaim(orderId)
// ...
const handleFulfill = () => {
fulfillClaim.mutate({
claim_id,
})
}
// ...
}
export default FulfillClaim
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
<!-- eslint-disable max-len -->
```ts
fetch(`<BACKEND_URL>/admin/orders/${orderId}/claims/${claimId}/fulfillments`, {
credentials: "include",
method: "POST",
})
.then((response) => response.json())
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/fulfillments' \
-H 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
</Tabs>
This endpoint requires the order and claim IDs as path parameters.
In the request body, you can pass optional parameters such as `metadata` or `no_notification`. These parameters will be used to create the fulfillment. You can learn more about available request body parameters in the [API reference](/api/admin#tag/Orders/operation/PostOrdersOrderClaimsClaimFulfillments).
The request returns the updated order as an object. You can access the order’s claims using the `claims` property of the order object. The value of the `claims` property is an array of claim objects.
### Create a Shipment
You can create a shipment for a claim by sending a request to the [Create Claim Shipment endpoint](/api/admin#tag/Orders/operation/PostOrdersOrderClaimsClaimShipments):
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.orders.createClaimShipment(orderId, claimId, {
fulfillment_id,
})
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminCreateClaimShipment } from "medusa-react"
const CreateShipment = () => {
const createShipment = useAdminCreateClaimShipment(orderId)
// ...
const handleCreate = () => {
createShipment.mutate({
claim_id,
fulfillment_id,
})
}
// ...
}
export default CreateShipment
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
<!-- eslint-disable max-len -->
```ts
fetch(`<BACKEND_URL>/admin/orders/${orderId}/claims/${claimId}/shipments`, {
credentials: "include",
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
fulfillment_id,
}),
})
.then((response) => response.json())
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/shipments' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
"fulfillment_id": "<FUL_ID>"
}'
```
</TabItem>
</Tabs>
This endpoint requires the order and claim IDs as path parameters.
In the request body, it’s required to pass the `fulfillment_id` parameter, which is the ID of the fulfillment the shipment is being created for. You can pass other optional parameters, such as an array of tracking numbers. You can learn more in the [API reference](/api/admin#tag/Orders/operation/PostOrdersOrderClaimsClaimShipments).
The request returns the updated order as an object. As mentioned before, a claim’s fulfillments can be accessed using the `fulfillments` property of a claim object. You can access the shipments, known as tracking links, of a fulfillment using the `tracking_links` property of a fulfillment object. The value of `tracking_links` is an array of tracking link objects.
You can alternatively access the tracking numbers using the `tracking_numbers` property of a fulfillment object, which is an array of strings.
You can access the status of a claim’s fulfillment using the `fulfillment_status` property of a claim object.
### Cancel Fulfillment
:::note
You can’t cancel a fulfillment that has a shipment
:::
You can cancel a fulfillment by sending a request to the [Cancel Fulfillment endpoint](/api/admin#tag/Orders/operation/PostOrdersClaimFulfillmentsCancel):
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.orders.cancelClaimFulfillment(
orderId,
claimId,
fulfillmentId
)
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminCancelClaimFulfillment } from "medusa-react"
const CancelFulfillment = () => {
const cancelFulfillment = useAdminCancelClaimFulfillment(
orderId
)
// ...
const handleCancel = () => {
cancelFulfillment.mutate({
claim_id,
fulfillment_id,
})
}
// ...
}
export default CancelFulfillment
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
<!-- eslint-disable max-len -->
```ts
fetch(`<BACKEND_URL>/admin/orders/${orderId}/claims/${claimId}/fulfillments/${fulfillmentId}/cancel`, {
credentials: "include",
method: "POST",
})
.then((response) => response.json())
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/fulfillments/<FUL_ID>/cancel' \
-H 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
</Tabs>
This endpoint requires the order, claim, and fulfillment IDs to be passed as path parameters.
The request returns the updated order as an object. You can access the claims using the `claims` property of the order object, which is an array of claim objects.
You can check the fulfillment status of a claim using the `fulfillment_status` property of the claim object.
---
## Cancel Claim
:::note
You can’t cancel a claim that has been refunded. You must also cancel the claim’s fulfillments and return first.
:::
You can cancel a claim by sending a request to the [Cancel Claim endpoint](/api/admin#tag/Orders/operation/PostOrdersClaimCancel):
<Tabs groupId="request-type" wrapperClassName="code-tabs">
<TabItem value="client" label="Medusa JS Client" default>
```ts
medusa.admin.orders.cancelClaim(orderId, claimId)
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="medusa-react" label="Medusa React">
```tsx
import { useAdminCancelClaim } from "medusa-react"
const CancelClaim = () => {
const cancelClaim = useAdminCancelClaim(orderId)
// ...
const handleCancel = () => {
cancelClaim.mutate(claimId)
}
// ...
}
export default CancelClaim
```
</TabItem>
<TabItem value="fetch" label="Fetch API">
<!-- eslint-disable max-len -->
```ts
fetch(`<BACKEND_URL>/admin/orders/${orderId}/claims/${claimId}/cancel`, {
credentials: "include",
method: "POST",
})
.then((response) => response.json())
.then(({ order }) => {
console.log(order.claims)
})
```
</TabItem>
<TabItem value="curl" label="cURL">
```bash
curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/cancel' \
-H 'Authorization: Bearer <API_TOKEN>'
```
</TabItem>
</Tabs>
This endpoint requires the order and claim IDs as path parameters.
The request returns the updated order as an object. You can access the claims using the `claims` property of the order object, which is an array of claim objects.
---
## See Also
- [How to manage returns](./manage-returns.mdx)
- [How to manage orders](./manage-orders.mdx)

13
docs/content/modules/orders/admin/manage-returns.mdx
View File

@@ -453,7 +453,7 @@ The request returns the order as an object. In that object, you can access an ar
## View a Swap’s Return
You can retrieve a swap either using the Get Order endpoint as explained here, or using the [List Swaps](/api/admin#tag/Swaps/operation/GetSwaps) or [Get Swap endpoint](/api/admin#tag/Swaps/operation/GetSwapsSwap).
You can retrieve a swap either using the Get Order endpoint as explained [here](./manage-swaps.mdx#view-orders-swaps), or using the [List Swaps](/api/admin#tag/Swaps/operation/GetSwaps) or [Get Swap endpoint](/api/admin#tag/Swaps/operation/GetSwapsSwap).
In a swap object, the swap’s return is available under the `return_order` property.
@@ -461,7 +461,7 @@ In a swap object, the swap’s return is available under the `return_order` prop
## View a Claim’s Return
You can retrieve a claim using the Get Order endpoint and accessing the `claims` property of the order object, which is an array of claim objects. In a claim object, the claim’s return is available under the `return_order` property.
You can retrieve a claim using the Get Order endpoint as explained [here](./manage-claims#view-orders-claims). In a claim object, the claim’s return is available under the `return_order` property.
---
@@ -639,13 +639,14 @@ This endpoint requires the return ID to be passed as a path parameter.
The request returns one of the following object types:
- If a return belongs to a swap, a swap object is returned.
- If a return belongs to a claim, a claim object is returned.
- Otherwise, an order object is returned.
- If a return belongs to a swap, a swap object is returned. You can access the returns in the `return_order` property of the swap object.
- If a return belongs to a claim, a claim object is returned. You can access the returns in the `return_order` property of the claim object.
- Otherwise, an order object is returned. You can access the returns in the `returns` property of the order object.
---
## See Also
- [How to manage orders using the REST APIs](./manage-orders.mdx)
- [How to manage swaps using the REST APIs](./manage-returns.mdx)
- [How to manage swaps using the REST APIs](./manage-swaps.mdx)
- [How to manage claims using the REST APIs](./manage-claims.mdx)

1
docs/content/modules/orders/claims.md
View File

@@ -149,5 +149,6 @@ You can access the claim’s fulfillment by expanding the `fulfillments` relatio
## See Also
- [How to manage claims using REST APIs](./admin/manage-claims.mdx)
- [Orders architecture overview](./orders.md)
- [Returns architecture overview](./claims.md)

3
docs/content/modules/orders/overview.mdx
View File

@@ -182,12 +182,11 @@ Customers can also request to return or swap items. This allows for implementing
},
{
type: 'link',
href: '#',
href: '/modules/orders/admin/manage-claims',
label: 'Admin: Manage Claims',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to manage claims using Admin APIs.',
isSoon: true,
}
},
{

3
packages/medusa/src/api/routes/admin/orders/fulfill-claim.ts
View File

@@ -36,7 +36,8 @@ import { updateInventoryAndReservations } from "./create-fulfillment"
* import Medusa from "@medusajs/medusa-js"
* const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
* // must be previously logged in or use api token
* medusa.admin.orders.fulfillClaim(order_id, claim_id)
* medusa.admin.orders.fulfillClaim(order_id, claim_id, {
* })
* .then(({ order }) => {
* console.log(order.id);
* });

15
www/docs/sidebars.js
View File

@@ -784,12 +784,9 @@ module.exports = {
label: "Admin: Manage Returns",
},
{
type: "link",
href: "#",
type: "doc",
id: "modules/orders/admin/manage-claims",
label: "Admin: Manage Claims",
customProps: {
sidebar_is_soon: true,
},
},
{
type: "link",
@@ -799,14 +796,6 @@ module.exports = {
sidebar_is_soon: true,
},
},
{
type: "link",
href: "#",
label: "Admin: Manage Return Reasons",
customProps: {
sidebar_is_soon: true,
},
},
{
type: "link",
href: "#",