Draft Orders

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

All hooks listed require authentication.

A draft order is an order created manually by the admin. It allows admins to create orders without direct involvement from the customer.

Related Guide: How to manage draft orders.

Mutations

useAdminCreateDraftOrder

This hook creates a Draft Order. A draft order is not transformed into an order until payment is captured.

Example

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

type DraftOrderData = {
  email: string
  region_id: string
  items: {
    quantity: number,
    variant_id: string
  }[]
  shipping_methods: {
    option_id: string
    price: number
  }[]
}

const CreateDraftOrder = () => {
  const createDraftOrder = useAdminCreateDraftOrder()
  // ...

  const handleCreate = (data: DraftOrderData) => {
    createDraftOrder.mutate(data, {
      onSuccess: ({ draft_order }) => {
        console.log(draft_order.id)
      }
    })
  }

  // ...
}

export default CreateDraftOrder

Mutation Function Parameters

AdminPostDraftOrdersReqAdminPostDraftOrdersReqRequired

The details of the draft order to create.

Mutation Function Returned Data

AdminDraftOrdersResAdminDraftOrdersResRequired

The list of draft orders.

useAdminUpdateDraftOrder

This hook updates a Draft Order's details.

Example

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

type Props = {
  draftOrderId: string
}

const DraftOrder = ({ draftOrderId }: Props) => {
  const updateDraftOrder = useAdminUpdateDraftOrder(
    draftOrderId
  )
  // ...

  const handleUpdate = (email: string) => {
    updateDraftOrder.mutate({
      email,
    }, {
      onSuccess: ({ draft_order }) => {
        console.log(draft_order.id)
      }
    })
  }

  // ...
}

export default DraftOrder

Hook Parameters

idstringRequired

The draft order's ID.

Mutation Function Parameters

AdminPostDraftOrdersDraftOrderReqAdminPostDraftOrdersDraftOrderReqRequired

The details of the draft order to update.

Mutation Function Returned Data

AdminDraftOrdersResAdminDraftOrdersResRequired

The list of draft orders.

useAdminDeleteDraftOrder

This hook deletes a Draft Order.

Example

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

type Props = {
  draftOrderId: string
}

const DraftOrder = ({ draftOrderId }: Props) => {
  const deleteDraftOrder = useAdminDeleteDraftOrder(
    draftOrderId
  )
  // ...

  const handleDelete = () => {
    deleteDraftOrder.mutate(void 0, {
      onSuccess: ({ id, object, deleted }) => {
        console.log(id)
      }
    })
  }

  // ...
}

export default DraftOrder

Hook Parameters

idstringRequired

The draft order's ID.

Mutation Function Returned Data

DeleteResponseDeleteResponseRequired

The response returned for a DELETE request.

useAdminDraftOrderRegisterPayment

This hook capture the draft order's payment. This will also set the draft order's status to completed and create an order from the draft order. The payment is captured through Medusa's system payment, which is manual payment that isn't integrated with any third-party payment provider. It is assumed that the payment capturing is handled manually by the admin.

Example

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

type Props = {
  draftOrderId: string
}

const DraftOrder = ({ draftOrderId }: Props) => {
  const registerPayment = useAdminDraftOrderRegisterPayment(
    draftOrderId
  )
  // ...

  const handlePayment = () => {
    registerPayment.mutate(void 0, {
      onSuccess: ({ order }) => {
        console.log(order.id)
      }
    })
  }

  // ...
}

export default DraftOrder

Hook Parameters

idstringRequired

The draft order's ID.

Mutation Function Returned Data

AdminPostDraftOrdersDraftOrderRegisterPaymentResAdminPostDraftOrdersDraftOrderRegisterPaymentResRequired

The order's details.

useAdminDraftOrderAddLineItem

This hook creates a Line Item in the Draft Order.

Example

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

type Props = {
  draftOrderId: string
}

const DraftOrder = ({ draftOrderId }: Props) => {
  const addLineItem = useAdminDraftOrderAddLineItem(
    draftOrderId
  )
  // ...

  const handleAdd = (quantity: number) => {
    addLineItem.mutate({
      quantity,
    }, {
      onSuccess: ({ draft_order }) => {
        console.log(draft_order.cart)
      }
    })
  }

  // ...
}

export default DraftOrder

Hook Parameters

idstringRequired

The draft order's ID.

Mutation Function Parameters

AdminPostDraftOrdersDraftOrderLineItemsReqAdminPostDraftOrdersDraftOrderLineItemsReqRequired

The details of the line item to create.

Mutation Function Returned Data

AdminDraftOrdersResAdminDraftOrdersResRequired

The list of draft orders.

useAdminDraftOrderRemoveLineItem

This hook deletes a Line Item from a Draft Order.

Example

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

type Props = {
  draftOrderId: string
}

const DraftOrder = ({ draftOrderId }: Props) => {
  const deleteLineItem = useAdminDraftOrderRemoveLineItem(
    draftOrderId
  )
  // ...

  const handleDelete = (itemId: string) => {
    deleteLineItem.mutate(itemId, {
      onSuccess: ({ draft_order }) => {
        console.log(draft_order.cart)
      }
    })
  }

  // ...
}

export default DraftOrder

Hook Parameters

idstringRequired

The draft order's ID.

Mutation Function Parameters

stringstringRequired

The ID of the line item to remove.

Mutation Function Returned Data

AdminDraftOrdersResAdminDraftOrdersResRequired

The list of draft orders.

useAdminDraftOrderUpdateLineItem

This hook updates a Line Item in a Draft Order.

Example

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

type Props = {
  draftOrderId: string
}

const DraftOrder = ({ draftOrderId }: Props) => {
  const updateLineItem = useAdminDraftOrderUpdateLineItem(
    draftOrderId
  )
  // ...

  const handleUpdate = (
    itemId: string,
    quantity: number
  ) => {
    updateLineItem.mutate({
      item_id: itemId,
      quantity,
    })
  }

  // ...
}

export default DraftOrder

Hook Parameters

idstringRequired

The draft order's ID.

Mutation Function Parameters

AdminDraftOrderUpdateLineItemReqAdminDraftOrderUpdateLineItemReqRequired

The details to update of the line item.

Mutation Function Returned Data

AdminDraftOrdersResAdminDraftOrdersResRequired

The list of draft orders.

---

Queries

useAdminDraftOrders

This hook retrieves an list of Draft Orders. The draft orders can be filtered by parameters such as query. The draft orders can also paginated.

Example

To list draft orders:

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

const DraftOrders = () => {
  const { draft_orders, isLoading } = useAdminDraftOrders()

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {draft_orders && !draft_orders.length && (
        <span>No Draft Orders</span>
      )}
      {draft_orders && draft_orders.length > 0 && (
        <ul>
          {draft_orders.map((order) => (
            <li key={order.id}>{order.display_id}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default DraftOrders

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 { useAdminDraftOrders } from "medusa-react"

const DraftOrders = () => {
  const { 
    draft_orders, 
    limit,
    offset,
    isLoading
  } = useAdminDraftOrders({
    limit: 20,
    offset: 0
  })

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {draft_orders && !draft_orders.length && (
        <span>No Draft Orders</span>
      )}
      {draft_orders && draft_orders.length > 0 && (
        <ul>
          {draft_orders.map((order) => (
            <li key={order.id}>{order.display_id}</li>
          ))}
        </ul>
      )}
    </div>
  )
}

export default DraftOrders

Hook Parameters

queryAdminGetDraftOrdersParams

Filters and pagination configurations to apply on the retrieved draft orders.

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.

draft_ordersDraftOrder[]Required

An array of draft order's details.

useAdminDraftOrder

This hook retrieves a Draft Order's details.

Example

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

type Props = {
  draftOrderId: string
}

const DraftOrder = ({ draftOrderId }: Props) => {
  const { 
    draft_order, 
    isLoading, 
  } = useAdminDraftOrder(draftOrderId)

  return (
    <div>
      {isLoading && <span>Loading...</span>}
      {draft_order && <span>{draft_order.display_id}</span>}
      
    </div>
  )
}

export default DraftOrder

Hook Parameters

idstringRequired

The draft order's ID.

Query Returned Data

draft_orderDraftOrderRequired

Draft order's details.