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.