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.

You can learn about managing returns part of a claim in the Manage Returns documentation.

---

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 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 installed and have created an instance of the client.

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 and have used MedusaProvider higher in your component tree.

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.

---

View Order’s Claims

To view an order’s claims, you can retrieve the order using the Get Order endpoint and access the order’s claims:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.retrieve(orderId)
.then(({ order }) => {
  console.log(order.claims)
})

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

fetch(`<BACKEND_URL>/admin/orders/${orderId}`, {
  credentials: "include",
})
.then((response) => response.json())
.then(({ order }) => {
  console.log(order.claims)
})

Report Incorrect CodeCopy to Clipboard

curl -L -X GET '<BACKEND_URL>/admin/orders/<ORDER_ID>' \
-H 'Authorization: Bearer <API_TOKEN>'

Report Incorrect CodeCopy to Clipboard

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 claimsCopy to Clipboard of the order object.

---

Create Claim

You can create a claim by sending a request to the Create Claim endpoint:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.createClaim(orderId, {
  type: "refund",
  claim_items: [
    {
      item_id,
      quantity: 1,
    },
  ],
})
.then(({ order }) => {
  console.log(order.claims)
})

Report Incorrect CodeCopy to Clipboard

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

Report Incorrect CodeCopy to Clipboard

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)
})

Report Incorrect CodeCopy to Clipboard

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
      }
    ]
}'

Report Incorrect CodeCopy to Clipboard

This endpoint requires the order ID to be passed as a path parameter.

In the request body, the following parameters are required:

• typeCopy to Clipboard: a string indicating the type of claim to be created. Its value can either be replaceCopy to Clipboard or refundCopy to Clipboard. If the type is replaceCopy to Clipboard, you can pass the additional_itemsCopy to Clipboard parameter with an array of new items to send to the customer. If the type is refundCopy to Clipboard, you can pass the refund_amountCopy to Clipboard parameter if you want to specify a custom refund amount.
• claim_itemsCopy to Clipboard: 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_idCopy to Clipboard: a string indicating the ID of the line item in the order.
  • quantityCopy to Clipboard: 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.

Learn how to manage return reasons in this documentation.

The request returns the updated order as an object. You can access the order’s claims using the claimsCopy to Clipboard property of the order object. The value of the claimsCopy to Clipboard property is an array of claim objects.

---

Update a Claim

You can update a claim by sending a request to the Update Claim endpoint:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.updateClaim(orderId, claimId, {
  no_notification: true,
})
.then(({ order }) => {
  console.log(order.claims)
})

Report Incorrect CodeCopy to Clipboard

import { useAdminUpdateClaim } from "medusa-react"

const UpdateClaim = () => {
  const updateClaim = useAdminUpdateClaim(orderId)
  // ...

  const handleUpdate = () => {
    updateClaim.mutate({
      claim_id,
      no_notification: true,
    })
  }

  // ...
}

export default UpdateClaim

Report Incorrect CodeCopy to Clipboard

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)
})

Report Incorrect CodeCopy to Clipboard

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
}'

Report Incorrect CodeCopy to Clipboard

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_notificationCopy to Clipboard field is updated.

The request returns the updated order as an object. You can access the order’s claims using the claimsCopy to Clipboard property of the order object. The value of the claimsCopy to Clipboard 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 fulfillmentsCopy to Clipboard 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:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.fulfillClaim(orderId, claimId, {
})
.then(({ order }) => {
  console.log(order.claims)
})

Report Incorrect CodeCopy to Clipboard

import { useAdminFulfillClaim } from "medusa-react"

const FulfillClaim = () => {
  const fulfillClaim = useAdminFulfillClaim(orderId)
  // ...

  const handleFulfill = () => {
    fulfillClaim.mutate({
      claim_id,
    })
  }

  // ...
}

export default FulfillClaim

Report Incorrect CodeCopy to Clipboard

fetch(`<BACKEND_URL>/admin/orders/${orderId}/claims/${claimId}/fulfillments`, {
  credentials: "include",
  method: "POST",
})
.then((response) => response.json())
.then(({ order }) => {
  console.log(order.claims)
})

Report Incorrect CodeCopy to Clipboard

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/fulfillments' \
-H 'Authorization: Bearer <API_TOKEN>'

Report Incorrect CodeCopy to Clipboard

This endpoint requires the order and claim IDs as path parameters.

In the request body, you can pass optional parameters such as metadataCopy to Clipboard or no_notificationCopy to Clipboard. These parameters will be used to create the fulfillment. You can learn more about available request body parameters in the API reference.

The request returns the updated order as an object. You can access the order’s claims using the claimsCopy to Clipboard property of the order object. The value of the claimsCopy to Clipboard 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:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.createClaimShipment(orderId, claimId, {
  fulfillment_id,
})
.then(({ order }) => {
  console.log(order.claims)
})

Report Incorrect CodeCopy to Clipboard

import { useAdminCreateClaimShipment } from "medusa-react"

const CreateShipment = () => {
  const createShipment = useAdminCreateClaimShipment(orderId)
  // ...

  const handleCreate = () => {
    createShipment.mutate({
      claim_id,
      fulfillment_id,
    })
  }

  // ...
}

export default CreateShipment

Report Incorrect CodeCopy to Clipboard

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)
})

Report Incorrect CodeCopy to Clipboard

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>"
}'

Report Incorrect CodeCopy to Clipboard

This endpoint requires the order and claim IDs as path parameters.

In the request body, it’s required to pass the fulfillment_idCopy to Clipboard 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.

The request returns the updated order as an object. As mentioned before, a claim’s fulfillments can be accessed using the fulfillmentsCopy to Clipboard property of a claim object. You can access the shipments, known as tracking links, of a fulfillment using the tracking_linksCopy to Clipboard property of a fulfillment object. The value of tracking_linksCopy to Clipboard is an array of tracking link objects.

You can alternatively access the tracking numbers using the tracking_numbersCopy to Clipboard property of a fulfillment object, which is an array of strings.

You can access the status of a claim’s fulfillment using the fulfillment_statusCopy to Clipboard property of a claim object.

Cancel Fulfillment

You can’t cancel a fulfillment that has a shipment

You can cancel a fulfillment by sending a request to the Cancel Fulfillment endpoint:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.cancelClaimFulfillment(
  orderId,
  claimId,
  fulfillmentId
)
.then(({ order }) => {
  console.log(order.claims)
})

Report Incorrect CodeCopy to Clipboard

import { useAdminCancelClaimFulfillment } from "medusa-react"

const CancelFulfillment = () => {
  const cancelFulfillment = useAdminCancelClaimFulfillment(
    orderId
  )
  // ...

  const handleCancel = () => {
    cancelFulfillment.mutate({
      claim_id,
      fulfillment_id,
    })
  }

  // ...
}

export default CancelFulfillment

Report Incorrect CodeCopy to Clipboard

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)
})

Report Incorrect CodeCopy to Clipboard

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/fulfillments/<FUL_ID>/cancel' \
-H 'Authorization: Bearer <API_TOKEN>'

Report Incorrect CodeCopy to Clipboard

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 claimsCopy to Clipboard property of the order object, which is an array of claim objects.

You can check the fulfillment status of a claim using the fulfillment_statusCopy to Clipboard property of the claim object.

---

Cancel Claim

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:

• Medusa JS Client
• Medusa React
• Fetch API
• cURL

medusa.admin.orders.cancelClaim(orderId, claimId)
.then(({ order }) => {
  console.log(order.claims)
})

Report Incorrect CodeCopy to Clipboard

import { useAdminCancelClaim } from "medusa-react"

const CancelClaim = () => {
  const cancelClaim = useAdminCancelClaim(orderId)
  // ...

  const handleCancel = () => {
    cancelClaim.mutate(claimId)
  }

  // ...
}

export default CancelClaim

Report Incorrect CodeCopy to Clipboard

fetch(`<BACKEND_URL>/admin/orders/${orderId}/claims/${claimId}/cancel`, {
  credentials: "include",
  method: "POST",
})
.then((response) => response.json())
.then(({ order }) => {
  console.log(order.claims)
})

Report Incorrect CodeCopy to Clipboard

curl -L -X POST '<BACKEND_URL>/admin/orders/<ORDER_ID>/claims/<CLAIM_ID>/cancel' \
-H 'Authorization: Bearer <API_TOKEN>'

Report Incorrect CodeCopy to Clipboard

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 claimsCopy to Clipboard property of the order object, which is an array of claim objects.

---

See Also

• How to manage returns
• How to manage orders