Skip to main content
Skip to main content

AdminOrdersResource

This class is used to send requests to Admin Order API Routes. All its method are available in the JS Client under the medusa.admin.orders property.

All methods in this class require user authentication.

Orders are purchases made by customers, typically through a storefront using CartsResource. Draft orders created by the admin are also transformed to an Order once the payment is captured. Managing orders include managing fulfillment, payment, claims, reservations, and more.

Related Guide: How to manage orders.

Methods​

update​

Update an order's details.

Example​

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.update(orderId, {
  email: "user@example.com"
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The order's ID.
payloadAdminPostOrdersOrderReqRequired
The attributes to update in the order.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

retrieve​

Retrieve an order's details.

Example​

A simple example that retrieves an order by its ID:

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.retrieve(orderId)
.then(({ order }) => {
  console.log(order.id);
})

To specify relations that should be retrieved:

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.retrieve(orderId, {
  expand: "customer"
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The order's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

queryFindParams
Configurations to apply on the retrieved order.

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

list​

Retrieve a list of orders. The orders can be filtered by fields such as status or display_id passed in the query parameter. The order can also be paginated.

Example​

To list orders:

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.list()
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length);
})

To specify relations that should be retrieved within the orders:

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.list({
  expand: "customers"
})
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length);
})

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

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.list({
  expand: "customers",
  limit,
  offset
})
.then(({ orders, limit, offset, count }) => {
  console.log(orders.length);
})

Parameters​

customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

queryAdminGetOrdersParams
Filters and pagination configurations applied on the retrieved orders.

Returns​

ResponsePromiseResponsePromise<AdminOrdersListRes>Required
Resolves to the list of orders with pagination fields.

complete​

Complete an order and change its status. A canceled order can't be completed.

Example​

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.complete(orderId)
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The order's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

capturePayment​

Capture all the payments associated with an order. The payment of canceled orders can't be captured.

Example​

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.capturePayment(orderId)
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order whose payments should be captured.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

refundPayment​

Refund an amount for an order. The amount must be less than or equal the refundable_amount of the order.

Example​

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.refundPayment(orderId, {
  amount: 1000,
  reason: "Do not like it"
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order whose customer should be refunded.
payloadAdminPostOrdersOrderRefundsReqRequired
The refund's details.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

createFulfillment​

Create a Fulfillment of an Order using the fulfillment provider, and change the order's fulfillment status to either partially_fulfilled or fulfilled, depending on whether all the items were fulfilled.

Example​

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.createFulfillment(orderId, {
  items: [
    {
      item_id,
      quantity: 1
    }
  ]
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the fulfillment belongs to.
payloadAdminPostOrdersOrderFulfillmentsReqRequired
The fulfillment to be created.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

cancelFulfillment​

Cancel an order's fulfillment and change its fulfillment status to canceled.

Example​

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.cancelFulfillment(orderId, fulfillmentId)
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the fulfillment belongs to.
fulfillmentIdstringRequired
The fulfillment's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

cancelSwapFulfillment​

Cancel a swap's fulfillment and change its fulfillment status to canceled.

Example​

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.cancelSwapFulfillment(orderId, swapId, fulfillmentId)
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the swap is associated with.
swapIdstringRequired
The ID of the swap the fulfillment belongs to.
fulfillmentIdstringRequired
The fulfillment's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

cancelClaimFulfillment​

Cancel a claim's fulfillment and change its fulfillment status to canceled.

Example​

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.cancelClaimFulfillment(orderId, claimId, fulfillmentId)
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the claim is associated with.
claimIdstringRequired
The claim's ID.
fulfillmentIdstringRequired
The fulfillment's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

createShipment​

Create a shipment and mark a fulfillment as shipped. This changes the order's fulfillment status to either partially_shipped or shipped, depending on whether all the items were shipped.

Example​

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.createShipment(order_id, {
  fulfillment_id
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order
payloadAdminPostOrdersOrderShipmentReqRequired
The shipment to be created.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

requestReturn​

Request and create a return for items in an order. If the return shipping method is specified, it will be automatically fulfilled.

Example​

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.requestReturn(orderId, {
  items: [
    {
      item_id,
      quantity: 1
    }
  ]
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The order's ID.
payloadAdminPostOrdersOrderReturnsReqRequired
The return to be created.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the return under the returns property.

cancel​

Cancel an order and change its status. This will also cancel any associated fulfillments and payments, and it may fail if the payment or fulfillment Provider is unable to cancel the payment/fulfillment.

Example​

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.cancel(orderId)
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The order's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

addShippingMethod​

Add a shipping method to an order. If another shipping method exists with the same shipping profile, the previous shipping method will be replaced.

Example​

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.addShippingMethod(orderId, {
  price: 1000,
  option_id
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The order's ID.
payloadAdminPostOrdersOrderShippingMethodsReqRequired
The shipping method to be added.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

archive​

Archive an order and change its status.

Example​

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.archive(orderId)
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The order's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details.

createSwap​

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

Example​

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.createSwap(orderId, {
  return_items: [
    {
      item_id,
      quantity: 1
    }
  ]
})
.then(({ order }) => {
  console.log(order.swaps);
})

Parameters​

idstringRequired
The order's ID.
payloadAdminPostOrdersOrderSwapsReqRequired
The swap to be created.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the swap under the swaps property.

cancelSwap​

Cancel a swap and change its status.

Example​

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.cancelSwap(orderId, swapId)
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the swap belongs to.
swapIdstringRequired
The swap's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the swap under the swaps property.

fulfillSwap​

Create 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 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.fulfillSwap(orderId, swapId, {
  no_notification: true,
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the swap belongs to.
swapIdstringRequired
The swap's ID.
payloadAdminPostOrdersOrderSwapsSwapFulfillmentsReqRequired
The fulfillment to be created.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the swap under the swaps property.

createSwapShipment​

Create 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 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.createSwapShipment(orderId, swapId, {
  fulfillment_id
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the swap belongs to.
swapIdstringRequired
The swap's ID.
payloadAdminPostOrdersOrderSwapsSwapShipmentsReqRequired
The shipment to be created.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the swap under the swaps property.

processSwapPayment​

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 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.processSwapPayment(orderId, swapId)
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the swap belongs to.
swapIdstringRequired
The swap's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the swap under the swaps property.

createClaim​

Create a claim for an order. If a return shipping method is specified, a return will also be created and associated with the claim. If the claim's type is refund, the refund is processed as well.

Example​

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.createClaim(orderId, {
  type: 'refund',
  claim_items: [
    {
      item_id,
      quantity: 1
    }
  ]
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The order's ID.
payloadAdminPostOrdersOrderClaimsReqRequired
The claim to be created.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the claim under the claims property.

cancelClaim​

Cancel a claim and change its status. A claim can't be canceled if it has a refund, if its fulfillments haven't been canceled, of if its associated return hasn't been canceled.

Example​

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.cancelClaim(orderId, claimId)
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the claim belongs to.
claimIdstringRequired
The claim's ID.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the swap under the claims property.

updateClaim​

Update a claim's details.

Example​

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.updateClaim(orderId, claimId, {
  no_notification: true
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the claim belongs to.
claimIdstringRequired
The claim's ID.
payloadAdminPostOrdersOrderClaimsClaimReqRequired
The attributes to update in the claim.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the claims under the claims property.

fulfillClaim​

Create a Fulfillment for a Claim, and change its fulfillment status to partially_fulfilled or fulfilled depending on whether all the items were fulfilled. It may also change the status to requires_action if any actions are required.

Example​

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(orderId, claimId, {
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the claim belongs to.
claimIdstringRequired
The claim's ID.
payloadAdminPostOrdersOrderClaimsClaimFulfillmentsReqRequired
The fulfillment to be created.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the swap under the claims property.

createClaimShipment​

Create a shipment for the claim and mark its fulfillment as shipped. If the shipment is created successfully, this changes the claim's fulfillment status to either partially_shipped or shipped, depending on whether all the items were shipped.

Example​

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.createClaimShipment(orderId, claimId, {
  fulfillment_id
})
.then(({ order }) => {
  console.log(order.id);
})

Parameters​

idstringRequired
The ID of the order that the claim belongs to.
claimIdstringRequired
The claim's ID.
payloadAdminPostOrdersOrderClaimsClaimShipmentsReqRequired
The shipment to create.
customHeadersRecord<string, any>Required
Custom headers to attach to the request.

Default: {}

Returns​

ResponsePromiseResponsePromise<AdminOrdersRes>Required
Resolves to the order's details. You can access the swap under the claims property.
Was this section helpful?
© 2024 Medusa, Inc. All rights reserved.