Swaps

Queries and Mutations listed here are used to send requests to the Admin Swap API Routes.

All hooks listed require user authentication.

A swap is created by a customer or an admin to exchange an item with a new one. Creating a swap implicitely includes creating a return for the item being exchanged.

Related Guide: How to manage swaps

Mutations

useAdminCreateSwap

This hook creates a swap for an order. This includes creating a return that is associated with the swap.

Example

import React from "react"
import { useAdminCreateSwap } from "medusa-react"

type Props = {
  orderId: string
}

const CreateSwap = ({ orderId }: Props) => {
  const createSwap = useAdminCreateSwap(orderId)
  // ...

  const handleCreate = (
    returnItems: {
      item_id: string,
      quantity: number
    }[]
  ) => {
    createSwap.mutate({
      return_items: returnItems
    }, {
      onSuccess: ({ order }) => {
        console.log(order.swaps)
      }
    })
  }

  // ...
}

export default CreateSwap

Hook Parameters

orderIdstringRequired

The associated order's ID.

Mutation Function Parameters

AdminPostOrdersOrderSwapsReqAdminPostOrdersOrderSwapsReqRequired

The details of the swap to create.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

The order's details.

useAdminCancelSwap

This hook cancels a swap and change its status.

Example

import React from "react"
import { useAdminCancelSwap } from "medusa-react"

type Props = {
  orderId: string,
  swapId: string
}

const Swap = ({
  orderId,
  swapId
}: Props) => {
  const cancelSwap = useAdminCancelSwap(
    orderId
  )
  // ...

  const handleCancel = () => {
    cancelSwap.mutate(swapId, {
      onSuccess: ({ order }) => {
        console.log(order.swaps)
      }
    })
  }

  // ...
}

export default Swap

Hook Parameters

orderIdstringRequired

The associated order's ID.

Mutation Function Parameters

stringstringRequired

The swap's ID.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

The order's details.

useAdminFulfillSwap

This hook creates a Fulfillment for a Swap and change its fulfillment status to fulfilled. If it requires any additional actions, its fulfillment status may change to requires_action.

Example

import React from "react"
import { useAdminFulfillSwap } from "medusa-react"

type Props = {
  orderId: string,
  swapId: string
}

const Swap = ({
  orderId,
  swapId
}: Props) => {
  const fulfillSwap = useAdminFulfillSwap(
    orderId
  )
  // ...

  const handleFulfill = () => {
    fulfillSwap.mutate({
      swap_id: swapId,
    }, {
      onSuccess: ({ order }) => {
        console.log(order.swaps)
      }
    })
  }

  // ...
}

export default Swap

Hook Parameters

orderIdstringRequired

The associated order's ID.

Mutation Function Parameters

AdminFulfillSwapReqAdminFulfillSwapReqRequired

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

The order's details.

useAdminCreateSwapShipment

This hook creates a shipment for a swap and mark its fulfillment as shipped. This changes the swap's fulfillment status to either shipped or partially_shipped, depending on whether all the items were shipped.

Example

import React from "react"
import { useAdminCreateSwapShipment } from "medusa-react"

type Props = {
  orderId: string,
  swapId: string
}

const Swap = ({
  orderId,
  swapId
}: Props) => {
  const createShipment = useAdminCreateSwapShipment(
    orderId
  )
  // ...

  const handleCreateShipment = (
    fulfillmentId: string
  ) => {
    createShipment.mutate({
      swap_id: swapId,
      fulfillment_id: fulfillmentId,
    }, {
      onSuccess: ({ order }) => {
        console.log(order.swaps)
      }
    })
  }

  // ...
}

export default Swap

Hook Parameters

orderIdstringRequired

The associated order's ID.

Mutation Function Parameters

AdminCreateSwapShipmentReqAdminCreateSwapShipmentReqRequired

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

The order's details.

useAdminProcessSwapPayment

This hook process a swap's payment either by refunding or issuing a payment. This depends on the difference_due of the swap. If difference_due is negative, the amount is refunded. If difference_due is positive, the amount is captured.

Example

import React from "react"
import { useAdminProcessSwapPayment } from "medusa-react"

type Props = {
  orderId: string,
  swapId: string
}

const Swap = ({
  orderId,
  swapId
}: Props) => {
  const processPayment = useAdminProcessSwapPayment(
    orderId
  )
  // ...

  const handleProcessPayment = () => {
    processPayment.mutate(swapId, {
      onSuccess: ({ order }) => {
        console.log(order.swaps)
      }
    })
  }

  // ...
}

export default Swap

Hook Parameters

orderIdstringRequired

The associated order's ID.

Mutation Function Parameters

stringstringRequired

The swap's ID.

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

The order's details.

useAdminCancelSwapFulfillment

This hook cancels a swap's fulfillment and change its fulfillment status to canceled.

Example

import React from "react"
import { useAdminCancelSwapFulfillment } from "medusa-react"

type Props = {
  orderId: string,
  swapId: string
}

const Swap = ({
  orderId,
  swapId
}: Props) => {
  const cancelFulfillment = useAdminCancelSwapFulfillment(
    orderId
  )
  // ...

  const handleCancelFulfillment = (
    fulfillmentId: string
  ) => {
    cancelFulfillment.mutate({
      swap_id: swapId,
      fulfillment_id: fulfillmentId,
    })
  }

  // ...
}

export default Swap

Hook Parameters

orderIdstringRequired

The associated order's ID.

Mutation Function Parameters

swap_idstringRequired

fulfillment_idstringRequired

Mutation Function Returned Data

AdminOrdersResAdminOrdersResRequired

The order's details.

---

Queries

useAdminSwaps

This hook retrieves a list of swaps. The swaps can be paginated.

Example

To list swaps:

import React from "react"
import { useAdminSwaps } from "medusa-react"

const Swaps = () => {
  const { swaps, isLoading } = useAdminSwaps()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {swaps && !swaps.length && <span>No Swaps</span>}
      {swaps && swaps.length > 0 && (
        <ul>
          {swaps.map((swap) => (
            <li key={swap.id}>{swap.payment_status}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default Swaps

By default, only the first 50 records are retrieved. You can control pagination by specifying the limit and offset properties:

import React from "react"
import { useAdminSwaps } from "medusa-react"

const Swaps = () => {
  const { 
    swaps, 
    limit,
    offset,
    isLoading
  } = useAdminSwaps({
    limit: 10,
    offset: 0
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {swaps && !swaps.length && <span>No Swaps</span>}
      {swaps && swaps.length > 0 && (
        <ul>
          {swaps.map((swap) => (
            <li key={swap.id}>{swap.payment_status}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default Swaps

Hook Parameters

queryAdminGetSwapsParams

Pagination configurations to apply on the retrieved swaps.

Query Returned Data

limitnumberRequired

The maximum number of items that can be returned in the list.

offsetnumberRequired

The number of items skipped before the returned items in the list.

countnumberRequired

The total number of items available.

swapsSwap[]Required

An array of swaps details.

useAdminSwap

This hook retrieves a swap's details.

Example

import React from "react"
import { useAdminSwap } from "medusa-react"

type Props = {
  swapId: string
}

const Swap = ({ swapId }: Props) => {
  const { swap, isLoading } = useAdminSwap(swapId)

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {swap && <span>{swap.id}</span>}
    </div>
  )
}

export default Swap

Hook Parameters

idstringRequired

The swap's ID.

Query Returned Data

swapSwapRequired

Swap details.