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 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
Parameters
id
stringRequiredThe attributes to update in the order.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredretrieve
Retrieve an order's details.
Example
A simple example that retrieves an order by its ID:
To specify relations that should be retrieved:
Parameters
id
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
query
FindParamsConfigurations to apply on the retrieved order.
query
FindParamsReturns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredlist
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:
To specify relations that should be retrieved within the orders:
By default, only the first 50
records are retrieved. You can control pagination by specifying the limit
and offset
properties:
Parameters
customHeaders
Record<string, any>RequiredDefault: {}
query
AdminGetOrdersParamsFilters and pagination configurations applied on the retrieved orders.
query
AdminGetOrdersParamsReturns
ResponsePromise
ResponsePromise<AdminOrdersListRes>RequiredResolves to the list of orders with pagination fields.
ResponsePromise
ResponsePromise<AdminOrdersListRes>Requiredcomplete
Complete an order and change its status. A canceled order can't be completed.
Example
Parameters
id
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredcapturePayment
Capture all the payments associated with an order. The payment of canceled orders can't be captured.
Example
Parameters
id
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredrefundPayment
Refund an amount for an order. The amount must be less than or equal the refundable_amount
of the order.
Example
Parameters
id
stringRequiredThe refund's details.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredcreateFulfillment
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
Parameters
id
stringRequiredThe fulfillment to be created.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredcancelFulfillment
Cancel an order's fulfillment and change its fulfillment status to canceled
.
Example
Parameters
id
stringRequiredfulfillmentId
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredcancelSwapFulfillment
Cancel a swap's fulfillment and change its fulfillment status to canceled
.
Example
Parameters
id
stringRequiredswapId
stringRequiredfulfillmentId
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredcancelClaimFulfillment
Cancel a claim's fulfillment and change its fulfillment status to canceled
.
Example
Parameters
id
stringRequiredclaimId
stringRequiredfulfillmentId
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredcreateShipment
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
Parameters
id
stringRequiredThe shipment to be created.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredrequestReturn
Request and create a return for items in an order. If the return shipping method is specified, it will be automatically fulfilled.
Example
Parameters
id
stringRequiredThe return to be created.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the return under the returns
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredreturns
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
Parameters
id
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredaddShippingMethod
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
Parameters
id
stringRequiredThe shipping method to be added.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredarchive
Archive an order and change its status.
Example
Parameters
id
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details.
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredcreateSwap
Create a swap for an order. This includes creating a return that is associated with the swap.
Example
Parameters
id
stringRequiredThe swap to be created.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the swap under the swaps
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredswaps
property.cancelSwap
Cancel a swap and change its status.
Example
Parameters
id
stringRequiredswapId
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the swap under the swaps
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredswaps
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
Parameters
id
stringRequiredswapId
stringRequiredThe fulfillment to be created.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the swap under the swaps
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredswaps
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
Parameters
id
stringRequiredswapId
stringRequiredThe shipment to be created.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the swap under the swaps
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredswaps
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
Parameters
id
stringRequiredswapId
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the swap under the swaps
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredswaps
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
id
stringRequiredThe claim to be created.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the claim under the claims
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredclaims
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
Parameters
id
stringRequiredclaimId
stringRequiredcustomHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the swap under the claims
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredclaims
property.updateClaim
Update a claim's details.
Example
Parameters
id
stringRequiredclaimId
stringRequiredThe attributes to update in the claim.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the claims under the claims
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredclaims
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
Parameters
id
stringRequiredclaimId
stringRequiredThe fulfillment to be created.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the swap under the claims
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredclaims
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
Parameters
id
stringRequiredclaimId
stringRequiredThe shipment to create.
customHeaders
Record<string, any>RequiredDefault: {}
Returns
ResponsePromise
ResponsePromise<AdminOrdersRes>RequiredResolves to the order's details. You can access the swap under the claims
property.
ResponsePromise
ResponsePromise<AdminOrdersRes>Requiredclaims
property.