How to Work With Orders?
The Order section of our API provides a powerful set of tools for managing the order lifecycle — from creation to handling returns and tracking deliveries. In this article, we will review the main methods available in this section of the API and their purposes.
To retrieve detailed information about a specific order, GET requests are used with the following endpoints:
order.info - returns complete information about an order by its identifier. You can use it to display order details to the user or administrator, or to integrate with other systems.
order.count - returns the total number of orders that match specific criteria (if provided in the request parameters). This can be useful for displaying statistics or for paginating order lists.
order.list - returns a list of orders with support for filtering, sorting, and pagination. This method is essential for displaying the order list in your admin interface or in the user's personal account.
order.abandoned.list - returns a list of abandoned carts. This can be used to analyze the reasons behind abandoned purchases and to send reminders to users.
order.shipment.info - returns information about a specific shipment by its identifier.
order.shipment.list - returns a list of shipments for a specific order with the ability to filter.
order.abandoned.list - returns a list of transactions associated with a specific order (e.g., payments, refunds).
Note: Some stores have certain restrictions on access to personal data, such as mobile phone numbers, addresses, and so on. To learn more about possible platform-specific limitations, refer to the relevant platform articles in the Integrations section.
If your platform supports multistore functionality, you need to pass the store_id parameter to retrieve orders for a specific store. The list of all stores, along with their corresponding store_id values, can be retrieved using the cart.info method from the stores_info field.
Filling in all order fields may require multiple requests to the store for each order, which can affect the overall request execution time. To ensure optimal performance, we recommend retrieving only the response fields that are truly necessary for your business logic. For this purpose, the response_fields parameter is used. Read more about response fields filtering.
It’s also important to optimize the number of orders returned in the response. If you need many fields in the response, it is recommended to retrieve no more than 50 orders per request. For this purpose, the count parameter is used.
For pagination, use the page_cursor parameter. You need to pass a cursor that points to the next or previous page. The cursor values for the next or previous page are returned in the response of the list method.
"pagination": {
"previous": null,
"next": "Dc9ZgkMwAADQA%2FmImdLGZyy1jJYSCfkbDYraokqdfubd4Bn5adYKKdwaQyZIcq6mbdH3dh3CIzt7rbViEc8QtFF9DIoykQi4cLd7xacOZ620oE6PZA%2B2tCKlV%2B2c8H0%2BnWP5Tn8GdUsOkb23ZpQwQe2B7BXFVi1jvanPU3mY1JzJUHWvtbbE%2Fh33i%2BEnvVFlrirbqHboIjetty3xMq%2BxAF39fcTsAiSUg8aqRu%2FHvOmI468rrri5QguNjnmXP3a0QrmndGqAdsOOd1eMwHbBNGJRamyHOgvZPvQkJfl7vgih%2F8c4Hy84fGajT9IZu1ORhGW%2BIaz9ouFmzm0TJPyze2dbeQQsj9PsHa55ByfDCQ4PF8YN4P5XPaQBQCVfhTJ8Xn2b%2FfoELuyU7o4Q%2FRg9bap9H1%2FpQ%2FGmiEq3p1ooxR8%3D"
}
Note: Some platforms return only a cursor for the next page, meaning that pagination is only possible in the forward direction. In such cases, it's recommended to use additional filters to reduce the total number of orders that need to be paginated.
Some platforms also support order sorting. For this purpose, the sort_by and sort_direction parameters are used. To get a list of fields that can be used for sorting on a specific platform, you can pass any clearly invalid value. The error message will include the list of supported sorting fields.
{
"return_code": 109,
"return_message": "Parameter 'sort_by' is not valid. The required type of parameter is enum. One of the following values are allowed: order_id, create_at, modified_at.",
"result": {}
}
Similarly, you can retrieve the list of available values for _status parameters (such as financial_status, fulfillment_status, etc.) by passing an intentionally invalid value. The error message will list the supported values.
Some platforms allow the creation of custom order status values. Therefore, to retrieve all possible order statuses, you should use the order.status.list method.
{
"return_code": 0,
"return_message": "",
"pagination": {
"previous": null,
"next": null
},
"result": {
"cart_order_statuses": [
{
"id": "open",
"name": "Open"
},
{
"id": "cancelled",
"name": "Cancelled"
},
{
"id": "closed",
"name": "Closed"
}
]
}
}
For the order_status value, you can pass either the id or the name from the response of this method.
The order.add method allows you to create an order. This method is not supported on all platforms — for example, on marketplaces, orders typically cannot be created via the API. To check whether a specific platform supports order creation, refer to the documentation to see if this method is available for the desired platform.
The list of required parameters for order creation varies significantly across platforms. However, two parameters are mandatory for all platforms: customer_email, which is used to identify the customer for whom the order will be created, and order_item, which specifies the products included in the order.
You can pass either the email of an existing customer or a new email in the customer_email field. In the case of a new email, a new customer will be created. This may require additional parameters needed to create the customer, such as first_name, last_name, phone, addresses, and others.
The order_item field should contain an array of products. In order_item_id, you must specify the product identifier, which can be retrieved using the product.list method. The order_item_quantity field is used to set the quantity of each product in the order. Some platforms also allow you to override the product name, SKU, price, and weight.
If a product is of type configurable or bundle, you need to use the product.child_item.list method to determine which specific variant of the product you want to include in the order. Then, pass the variant identifier in the order_item_variant_id field.
If a product includes options, you need to specify them using the order_item_option field. The list of available options, their names, and values can be retrieved using the product.info method.
All totals are calculated automatically based on product prices, shipping method, and other factors. However, if the platform supports it, you can manually specify exact values for totals, subtotals, shipping costs, tax amounts, discounts, and more.
For some platforms, it is mandatory to specify a shipping method when creating an order. To calculate the shipping cost and obtain a list of available shipping methods for a given address, you should use the order.preestimate_shipping.list method. At the moment, this method is supported only for the Magento 2 API integration.
The order.update method allows you to update order statuses, including payment and fulfillment statuses, as well as add comments.
When creating or updating an order, there is an option to send an email notification to the customer. To enable this, you need to set send_notifications=true.
To learn more about what each parameter is used for and whether it is supported on a specific platform, refer to our documentation.
Work with Shipments
The order.shipment.list method allows you to retrieve a list of shipments for a specified order.
To create a shipment for an order, you need to use the order.shipment.add method. In this method, you must specify the order identifier (order_id) for which the shipment will be created, as well as the tracking_numbers, where you need to provide the carrier identifier (carrier_id) and the tracking number (tracking_number).
The list of available carrier_id values can be retrieved using the cart.info method in the carrier_info field. Some platforms allow you to specify a custom value for the carrier_id.
To create a partial shipment, you need to provide an items array, where each item includes the order_product_id - a unique identifier of the product within the specific order and quantity, which indicates how many units of the product should be shipped. Use the order.info method to retrieve the product identifier (order_products->order_product_id).
You can also specify the warehouse from which the products will be shipped by providing the warehouse_id. The list of available warehouses can be retrieved using the cart.info method in the warehouses field.
We also provide the order.shipment.add.batch method, which allows you to create shipments for multiple orders at once.
The order.shipment.tracking.add method allows you to add a tracking number to an existing shipment.
To update the data for a specific shipment, you need to use the order.shipment.update method.
To delete a shipment, you need to use the order.shipment.delete method.
Note: that to use shipment functionality on WooCommerce, you need to have a specific extension installed. At the moment, we support plugins Shipment Tracking for WooCommerce and Advanced Shipment Tracking for WooCommerce.
Work with Returns
The API also provides functionality for handling product returns:
order.return.add - allows to register a return request from a customer.
order.return.update - allows to update the status or other information related to a return request.
order.return.update - allows to delete a return request.
order.refund.add - used to initiate the refund process for an order or part of it.
Note: that to use returns functionality on WooCommerce, you need to have a specific extension installed. At the moment, we support plugin Return Refund and Exchange For WooCommerce.
For more details on working with returns, please refer to the corresponding article. Read more about how to work with refunds here.
To initiate a refund, the order must be paid.
To create a refund, you need to specify the order identifier (order_id) for which the refund will be issued, and the products from the order (items) that are to be refunded. If items are not specified, the refund will be issued for all products. You can also specify the exact amounts to be refunded (for the product, shipping, fee, or total), but these amounts must not exceed the original amounts paid.
You can retrieve refund information using the order.info method. The status->refund_info field displays the total amount refunded, while the refunds field provides detailed data about each individual refund associated with the order.
{
"result": {
"order_id": "1",
"status": {
"id": "closed",
"name": "Closed",
"history": [
{
"id": "open",
"name": "Open",
"modified_time": {
"value": "2022-09-23T13:08:03+0300",
"format": "Y-m-d\\TH:i:sO"
},
"notify": false,
"comment": ""
},
{
"id": "closed",
"name": "Closed",
"modified_time": {
"value": "2023-01-20T15:09:46+0200",
"format": "Y-m-d\\TH:i:sO"
},
"notify": false,
"comment": ""
}
],
"refund_info": {
"shipping": 0,
"fee": 0,
"tax": 2.5,
"total_refunded": 15,
"time": {
"value": "2023-01-20T15:09:46+0200",
"format": "Y-m-d\\TH:i:sO"
},
"comment": "",
"refunded_items": [
{
"product_id": "1",
"variant_id": null,
"order_product_id": "1",
"qty": 1,
"refund": 15
}
]
}
},
"refunds": [
{
"id": "1",
"shipping": 0,
"fee": 0,
"tax": 2.5,
"total": 15,
"modified_time": {
"value": "2023-01-20T15:09:46+0200",
"format": "Y-m-d\\TH:i:sO"
},
"comment": "",
"items": [
{
"product_id": "1",
"variant_id": null,
"order_product_id": "1",
"qty": 1,
"refund": 15
}
]
}
]
}
}
