API Order Management
Order management operations can be automated through the Admin API for more efficient operations and bulk actions on large quanities of orders.
Below are best practices and guides for common scenarios merchants and partners use to manage orders on the Admin API.
Order Items Editing
Editing items on an order is common practice, such as swapping products purchased for a different size or color with the same value without needing to collect payment or create a refund.
Only Available on 2024-04-01 API Version
Order editing APIs are only available on 2024-04-01 API Version and above, if you are still using older versions we recommend you upgrade your integration.
Order editing APIs also do not affect order payment within each request. To remove items with an associated refund, see order refunds. Using order edit APIs can result in the customer owing or the merchant owing to the customer.
Line Item Quantities Explained
Order line items have 4 quantity attributes that represent quantities at different states in an order life cycle.
quantity- Item quantity total ever added to the order in this line.current_quantity- Current item quantity that have not yet been removed.fulfillable_quantity- Item quantity that have not yet been fulfilled, such as a partial fulfillment.editable_quantity- Item quantity that currently can be edited.
"lines": [
{
...
"quantity": 3, // quantity of items ever added
"current_quantity": 2, // current quantity that have not been removed
"fulfillable_quantity": 1, // quantity that have not yet been fulfilled
"editable_quantity": 1, // quantity that can be edited
...
}
]Swap Items Flow
Swapping Items on an order is a 4 step process:
- Retrieve order line items using the ordersRetrieve endpoint and check
editable_quantityis > 0. - Update/Remove line items using the ordersLinesPartialUpdate or ordersLinesDestroy endpoint.
- Create new line item ordersLinesCreate endpoint.
- Collect payment for an outstanding balance using the ordersCollectPaymentCreate endpoint.
Update Existing Line Item
Below is an example API call to change the quantity of a line item to 1. If the existing quantity was 2, this would remove 1 quantity, can also be used to increase line item quantity. This endpoint only accepts quantity changes, to change the product or price, see ordersLinesCreate endpoint.
{
"quantity": 1, // change quantity to 1
"reason": "product swap" // optional
}Remove Full Line Item
Below is an example DELETE request to the ordersLinesDestroy endpoint to remove a line item.
{}Check Line Item Editable Quantity
Line items have editable_quantity which represents the item quantity not already in process of being fulfilled, already fulfilled, or already removed from the order.
If editable_quantity is 0, the line item cannot be edited.
Create New Line Item
Below is an example POST request to the ordersLinesCreate endpoint to create a new line item.
{
"product_id": 184, // product variant id
"quantity": 1,
"price": 89.99, // optional
"reason": "product swap" // optional
}Collect Payment for Outstanding Balance
Orders can have an outstanding balance owed by the customer as a result of changing items on the order. To collect the outstanding balance, use the ordersCollectPaymentCreate endpoint to initate a payment transaction with the order's initial payment method.
{
"send_payment_notification": true // optionally send notificaiton to customer
}Order Refunds
Order management actions that require refunding and removing items from an order can be done through the refund flow. The refund flow is espcially useful when creating partial refunds or creating refunds for items that have already shipped to the customer.
Refund Flow
Refunding specific items of an order is a 3-step process:
- Retreive order line items using the ordersRetrieve endpoint.
- Calculate the refund using the ordersRefundCalculateCreate endpoint.
- Create the refund using the ordersRefundCreate endpoint.
Order Refund Calculate APIs are only available on 2024-04-01 version and newer. See API Versioning for how to specify a version in your requests.
Retrieve Order Lines
Below is an abreviated example request to ordersRetrieve endpoint to get the line items of the order.
{
"lines": [
{
"id": 1000, // order line item
"quantity": 3, // quantity in the order
"current_quantity": 3 // quantity available and not yet removed from the order
}
]
}Order Payments Must Be Captured
Order payments must be captured in order to create partial refunds, uncaptured payments cannot be partially refunded.
Calculate Refund
Call the ordersRefundCalculateCreate endpoint with your line items to calculate the refund and see which initial payment transactions will be refunded.
{
"refund_lines": [
{
"line_id": 1000, // line item we want to refund
"quantity": 1 // quantity to refund
}
],
"refund_shipping": {
"full_refund": false, // set true to fully refund shipping
"amount_excl_tax": "3.99"
}
}Below is the response from the ordersRefundCalculateCreate API that has been slightly abbreviated to focus on the relevant refund items.
{
"refund_lines": [
{
"line_id": 1000, // line item being refunded
"quantity": 1, // number of items being refunded
"restock_type": "no_restock", // restock action, see notes
"refundable_quantity": 1, // items that can be refunded
"amount_excl_tax": "59.99", // amount to be refunded excl tax
"amount_incl_tax": "59.99", // amount to be refunded incl tax
"total_tax": "0.00" // total tax on this line item to refund
}
],
"refund_shipping": {
"amount_incl_tax": "3.99", // amount to be refunded incl tax
"amount_excl_tax": "3.99", // amount to be refunded excl tax
"total_tax": "0.00", // shipping tax to be refunded
"refundable_amount": "4.99" // shipping amount avialable to refund
},
"transactions": [
{
"id": 1000, // transaction the refund will be allocated to, can be multiple.
"amount": "63.98", // amount being refunded on this transaction
"refundable_amount": "184.96" // amount available to refund with this transaction
}
],
"amount_excl_tax": "63.98", // total amoutn excl tax being refunded
"amount_incl_tax": "63.98", // total amount incl to be refunded
"total_tax": "0.00", // total tax being refunded
"currency": "USD"
}Create Refund
We're now ready to create a refund using the ordersRefundCreate endpoint, see request details below.
{
"note": "Example reason for the refund",
"refund_lines": [
{
"line_id": 1000, // line item being refunded
"quantity": 1, // number of items being refunded
"restock_type": "no_restock", // restock action (from calculate step)
}
],
"refund_shipping": {
"amount_excl_tax": "3.99",
"full_refund": false
},
"send_refund_notification": true, // send refund email notification to customer
"transactions": [
{
"id": 1000, // transaction id to refund (from calculate step)
"amount": "63.98" // amount to refund to this transaction (from calculate step)
}
]
}Restock Actions
Depending on the product type and status of the line items being refunded, there are differen't restock actions available.
Physical Product
- If unfulfilled, restock_type must be
cancel. - If fullfilled, restock_type can be
returnorno_restock.
Digital Product
- If unfulfilled, restock_type must be
cancel. - If fulfilled, restock_type must be
no_restock.
Update Shipping Address
Updating an order shipping address is a common task that can be done with a PATCH request to the ordersUpdate endpoint.
{
"shipping_address": {
"line1": "4765 Test Lane West", // new shipping address line 1
"line4": "Mountain Pass", // new shipping address city
"state": "CA", // new shipping address state
"postcode": "92366", // new shipping address postcode
"country": "US" // new shipping address country
}
}Before Fulfillment Processing
Updating an order shipping address should be done before the order is sent to a fulfillment location for fulfillment. If the order has already been accepted and processing, send a a cancellationRequestSend request and then fulfillmentRequestSend after you've updated the shipping address.
Request Fulfillment
Fulfillment can be requested immediately through the fulfillmentRequestSend for cases that you'd like to immediately send the fulfillment order to the fulfillment location for fulfillment.
{
"fulfillment_order_line_items": [ // will split the fulfillment order into a new fulfillment order
{
"id": 0,
"quantity": 1
}
],
"message": "Special message to warehouse", // message to the fulfillment location
"notify": true // notify the customer when fulfillment order is fulfilled
}Hold Fulfillment
Holding fulfillment for an order while waiting for additional review or making adments to the order before sending to the fulfillment location for shipping.
- Retrieve all fulfillment Orders using the ordersFulfillmentOrdersRetrieve endpoint.
- Send a fulfillmentOrdersHold request for each fulfillment order to hold.
{
"reason": "address_incorrect", // see available reasons in api reference
"reason_message": "Additional relevant detail." // provide additional relevant detail
}Cancel Fulfillment
Canceling a fulfillment order that is already accepted and processing with a fuflillment location is a common order management task to stop fulfillment or as a prerequisite step to moving a fulfillment order to a new location.
- Retrieve all fulfillment Orders using the ordersFulfillmentOrdersRetrieve endpoint.
- Send a cancellationRequestSend request for each fulfillment order to request fulfillment cancellation.
{
"message": "Reason why canceling fulfillment" // message sent to the fulfillment location
}Move Fulfillment Orders
Moving a fulfillment order items to a new fulfillment location is a common order management task when items cannot be fulfilled by the currently assigned location and need to be requested with a new fulfillment location.
Move Fulfillment Order Flow
Moving fulfillment order items is a 2-step process:
- Retrieve available locations for items to move using the availableLocationsRetrieve endpoint.
- Move fulfilllment order line items to a new location using the fulfillmentOrdersMove endpoint.
Fulfillment Orders must be "status": "open" to be moved to a new location. If the fulfillment order you want to move is "status": "processing", use the cancellationRequestSend endpoint to request cancellation with the current fulfillment location before moving to a new location.
Retrieve Available Locations
Fulfillment order line items often contain products that are in stock at many locations where they could be fulfilled from. To check what locations fulfillment order items are available at, use the availableLocationsRetrieve endpoint.
{
"available_locations": [
{
"id": 123,
"name": "Example Warehouse Location",
"fulfillment_order_line_ids": [
7731,
7730
]
},
{
"id": 456,
"name": "Another Warehouse Location",
"fulfillment_order_line_ids": [
7731
]
}
]
}Move a Fulfillment Order
Once the available locations fulfillment order line items can move, use the fulfillmentOrdersMove endpoint to move all or some of the line items.
{
"new_location_id": 123,
/// optional, if not passed, all lines will be moved to the new location
"fulfillment_order_line_items": [
{
"id": 7711
}
]
}Cancel Order
Canceling an order is a common order management task when you need to cancel the entire order and refund all payment transactions. To cancel an order, send a request to the ordersCancelCreate endpoint.
{
"cancel_reason": "Customer wants to cancel", // Appropiate cancel reason message
"full_refund": true, // Refund all remainaing payments or not
"send_cancel_notification": true // Send the customer a notification or not
}