Orders are what an online store is about. Customers submit orders at checkout after adding at least one product to cart. Administrators can work with the submitted orders and add new orders themselves.
To get a list of orders, send a GET request to /api/orders/
:
GET /api/orders/
This request returns 10 orders with a short list of details for each order.
Add these parameters to the path to specify what orders will be returned in the response and how they will be organized:
Parameter | Default value | Description |
---|---|---|
page | 1 | The response to GET /api/orders/ is a page with a limited number of orders. This parameter determines the number of the page that will be sent in the response. |
items_per_page | 10 | Determines the number of orders on a page. |
sort_by | date |
Determines the parameter by which the orders are sorted in the response. |
sort_order | desc |
Determines the sorting order:
asc —ascendingdesc —descending |
status | Searches only for the orders with the specified status. Status names and functions are configured by store owners and may vary from store to store.
These default order statuses can be edited, but can’t be deleted:
P —processedC —completeO —openF —failedD —declinedB —backorderedI —cancelledY —awaiting call |
|
user_id | Searches only for the orders placed the customer with the specified ID. | |
company_id | Searches only for the orders placed on the specific storefront (in CS-Cart) or at the specific vendor (in Multi-Vendor). | |
Searches only for the orders placed by the customer with the specified email. | ||
invoice_id | Searches only for the orders with the specified invoice ID. | |
credit_memo_id | Searches only for the orders with the specified credit memo ID. |
Examples:
GET /api/orders/?page=5&items_per_page=5&status=C
Response is an array with 5 orders from the 5th page of the list of complete orders.
GET /api/orders/?email=customer@example.com&company_id=2
Response is an array with 10 orders placed by the customer with the specified email at the storefront (in CS-Cart) or with the vendor (in Multi-Vendor) with company_id=2
.
Let’s make a test request:
GET /api/orders/?items_per_page=2
If the request is successful, you’ll receive HTTP/1.1 200 OK. The response is JSON with the following data:
{
"orders": [
{
"order_id": "97",
"issuer_id": null,
"user_id": "3",
"is_parent_order": "N",
"parent_order_id": "0",
"company_id": "1",
"timestamp": "1456917981",
"firstname": "George",
"lastname": "Nills",
"email": "[email protected]",
"phone": "+1 646-386-3600",
"status": "O",
"total": "677.95",
"invoice_id": null,
"credit_memo_id": null,
"points": null
},
{
"order_id": "96",
"issuer_id": null,
"user_id": "3",
"is_parent_order": "N",
"parent_order_id": "0",
"company_id": "1",
"timestamp": "1456917981",
"firstname": "Customer",
"lastname": "Customer",
"email": "[email protected]",
"phone": "",
"status": "C",
"total": "972.00",
"invoice_id": null,
"credit_memo_id": null,
"points": null
}
],
"params": {
"page": 1,
"items_per_page": "2",
"ajax_custom": "1",
"include_incompleted": false,
"sort_order": "desc",
"sort_by": "date",
"sort_order_rev": "asc",
"total_items": "64"
}
}
To get the full list of details of a specific order, send a GET request to /api/orders/<order_id>/
. For example:
GET /api/orders/100
The fields below represent various order details.
Note
The CS-Cart/Multi-Vendor REST API always accepts and returns data as strings and arrays/objects. The Values column in the table merely shows what kind of data you can expect in the fields.
Field | Values | Description |
---|---|---|
order_id | integer | A unique identifier of the order. |
is_parent_order | Y —yesN —no |
Multi-Vendor uses parent orders internally to process the initial order via the payment processor. Parent orders don’t appear on the order list in the Administration panel. |
parent_order_id | integer | If an order includes products from several vendors, then a parent order and separate orders for each vendor are created. These separate orders are linked to the ID of the parent order. |
status | string | The status of the order. A unique letter of the English alphabet is assigned to every order status as a means to refer to it. |
timestamp | integer | The UNIX time when the order was placed. |
company_id | integer | ID of the associated storefront (in CS-Cart) or vendor (in Multi-Vendor). |
issuer_id | integer | ID of the administrator who created the order via the admin panel. |
user_id | integer | A unique identifier of the user who placed the order. Orders placed by guests have user_id=0 . |
firstname | string | Customer’s first name. |
lastname | string | Customer’s last name. |
string | Customer’s email. | |
phone | string | Customer’s phone number. |
ip_address | string | Customer’s IP address. |
lang_code | string | The code of the language which the customer selected when placing the order, for example en . |
localization_id | integer | ID of the localization. Note: Localizations are deprecated and disabled by default. |
total | float | The sum to be paid by the customer. |
discount | float | Total discount. |
subtotal | float | The order subtotal. |
subtotal_discount | float | Discount on the order subtotal. |
display_subtotal | float | The subtotal that will be displayed. |
invoice_id | integer | ID of the invoice. |
credit_memo_id | integer | ID of the credit memo. |
payment_id | integer | ID of the payment method. |
payment_info | array | Payment information. |
payment_method | object | The settings of the payment method. |
payment_surcharge | float | The amount of payment surcharge. |
repaid | 0 —no1 —yes |
Defines if the order was repaid. |
products | object | The information about the ordered products. |
promotion_ids | string | A string of promotion IDs separated by commas. |
promotions | array | The data of applicable promotions. |
need_shipping | true false |
Defines if the order requires shipping. |
shipping_ids | string | IDs of the shipping methods. |
shipping | array | The data of the shipping methods used in the order. |
shipping_id | integer | ID of the shipping method. |
need_shipment | true false |
Defines if the order requires shipments. |
shipment_ids | string | A string of shipment IDs separated by commas. |
shipping_cost | float | The shipping cost. |
display_shipping_cost | float | The shipping cost that will be displayed. |
tax_exempt | Y —yesN —no |
Determines if the customer is exempt from taxes. |
tax_subtotal | float | Subtotal tax. |
taxes | object | The data of the applicable taxes. |
notes | string | Customer’s notes about the order. |
details | string | Administrator’s notes about the order. |
s_address | string | Shipping address (the first field). |
s_address_2 | string | Shipping address (the second field). |
s_city | string | City (shipping address). |
s_country | string | A 2-letter country code (shipping address). |
s_country_descr | string | Country name (shipping address). |
s_firstname | string | First name (shipping address). |
s_lastname | string | Last name (shipping address). |
s_phone | string | Phone number (shipping address). |
s_state | string | State code (shipping address). |
s_state_descr | string | State name (shipping address). |
s_zipcode | string | Zip code (shipping address). |
b_address | string | Billing address (the first field). |
b_address_2 | string | Billing address (the second field). |
b_city | string | City (billing address). |
b_country | string | A 2-letter country code (billing address). |
b_country_descr | string | Country name (billing address). |
b_firstname | string | First name (billing address). |
b_lastname | string | Last name (billing address). |
b_phone | string | Phone number (billing address). |
b_state | string | State code (billing address). |
b_state_descr | string | State name (billing address). |
b_zipcode | string | Zip code (billing address). |
CS-Cart | Send a POST request to /api/stores/<company_id>/orders/ |
---|---|
Multi-Vendor | Send a POST request to /api/orders/ |
Important
A newly-created order will always have "status": "O"
. You can change it only when you update an order.
Pass the following fields with order details in the HTTP request body in accordance with the Content-Type
. Required fields are marked with *:
user_id*—the unique identifier of the user. Can be omitted or set to 0 only if the request includes user_data
.
payment_id*—ID of the payment method. The payment method must be available in the store.
shipping_id*—ID of the shipping method. The shipping method must be available in the store and configured to calculate the cost of shipping to the address you pass in the request.
Beginning with version 4.3.7, you can specify an array of shipping method IDs as the value of shipping_id
. The keys of the array would be the keys of the product groups in the cart.
This comes useful when you create an order with the products from multiple vendors (in Multi-Vendor), or from multiple suppliers, or whenever else the products in the cart are separated into groups.
products*—an object (associative array) with the information about the ordered products. There are two ways how you can specify a product:
Way 1: Product IDs serve as the keys, and the values are product details:
"products": {
"241": {
"amount": "1",
"product_options": {
"12": "44",
"13": "48"
}
}
}
Important
If you want your order to have multiple instances of the same product, but with different selected options and option combination, don’t use product IDs as keys; use Way 2 instead.
Way 2: Keys are random numbers, and product IDs are included in the values among other product details:
"products": {
"1": {
"product_id": "12",
"amount": "1",
"product_options": {
"3": "12",
"4": "17"
}
},
"2": {
"product_id": "12",
"amount": "2",
"product_options": {
"3": "15",
"4": "19"
}
}
}
Note
Product price is taken from the product settings, not from the JSON data. A discount
on product can’t be specified in the POST request, but only in the PUT request.
user_data—an object (associative array) with the customer’s data. If you specify a user_id
other than 0, this parameter won’t be considered and can be omitted. If user_id
is omitted or set to 0, user_data
is required:
"user_data": {
"email": "[email protected]",
"b_firstname": "John",
"b_lastname": "Doe",
"b_address": "44 Main street",
"b_city": "Boston",
"b_state": "MA",
"b_country": "US",
"b_zipcode": "02134",
"b_phone": "",
"s_firstname": "John",
"s_lastname": "Doe",
"s_address": "44 Main street",
"s_city": "Boston",
"s_state": "MA",
"s_country": "US",
"s_zipcode": "02134",
"s_phone": ""
}
Note
You can view the available country and state codes in the Administration panel of your store under Administration → Shipping & Taxes → States.
CS-Cart | Send a POST request to /api/stores/<company_id>/orders/ |
---|---|
Multi-Vendor | Send a POST request to /api/orders/ |
Required fields: user_id
, payment_id
, shipping_id
, products
Example JSON:
{
"user_id": "3",
"shipping_id": "1",
"payment_id": "2",
"products": {
"1": {
"product_id": "12",
"amount": "1"
},
"2": {
"product_id": "13",
"amount":"2"
}
}
}
This request places an order with the following properties:
user_id=3
.shipping_id=1
was chosen.payment_id=2
was chosen.product_id=12
and two products with product_id=13
were ordered.{
"user_id": "3",
"shipping_id": "1",
"payment_id": "2",
"products": {
"1": {
"product_id": "12",
"amount": "5"
},
"2": {
"product_id": "13",
"amount":"2"
}
},
"coupon_codes": {
"1": "123"
}
}
This request:
123
to the order;CS-Cart | Send a POST request to /api/stores/<company_id>/orders/ |
---|---|
Multi-Vendor | Send a POST request to /api/orders/ |
Required fields: user_data
, payment_id
, shipping_id
, products
Example JSON:
{
"user_id": "0",
"payment_id": "2",
"shipping_id": "1",
"products": {
"1": {
"product_id": "12",
"amount": "1"
},
"2": {
"product_id":"13",
"amount":"2"
}
},
"user_data": {
"email":"[email protected]",
"firstname": "Guest",
"lastname": "Guest",
"s_firstname": "Guest",
"s_lastname": "Guest",
"s_country": "US",
"s_city": "Boston",
"s_state": "MA",
"s_zipcode": "02125",
"s_address": "44 Main street",
"b_firstname": "Guest",
"b_lastname": "Guest",
"b_country":"US",
"b_city": "Boston",
"b_state": "MA",
"b_zipcode":"02125",
"b_address": "44 Main street"
}
}
This request is similar to the previous example, but the order is placed on behalf of a guest with the specified contact details.
Note
Guests specify their address and contact information at checkout. That’s why you must pass the user_data
object in the JSON when you place an order on behalf a guest.
The order has been created successfully: HTTP/1.1 201 Created and the order ID:
{
"order_id": "98"
}
The order couldn’t be created: HTTP/1.1 400 Bad Request.
To update an existing order, send the PUT request to /api/orders/<order_id>/
. For example:
PUT /api/orders/98
Pass the fields with order details in the HTTP request body in accordance with the passed Content-Type
. None of the fields are required.
By default, when you change the order status via REST API, no email notifications are sent. However, you can use additional fields when updating an order, with 0 or 1 as values:
notify_user—this flag determines whether or not to send the notification to the customer.
notify_department—this flag determines whether or not to send the notification to the order department.
notify_vendor—this flag determines whether or not to send the notification to the vendor.
Note
The notify_vendor flag is available only in Multi-Vendor.
{
"status": "P",
"notify_user": "1",
"notify_department": "1",
"notify_vendor": "1"
}
This request sets the status of the order to P
(Processed by default) and sends email notifications to the customer, the vendor, and the order department.
{
"products": {
"1": {
"product_id": "12",
"amount": "1"
},
"3": {
"product_id": "241",
"amount": "1",
"product_options": {
"12": "44",
"13": "48"
}
}
}
}
This request changes the products assigned to the order. When we created order 98, it had one product with product_id=12
and two products with product_id=13
. After this request the order will have one product with product_id=12
, and one product with product_id=241
.
As you can see, product 241 also has the option variants selected:
Note
If an order has multiple products, make sure to specify them all when you update the products
object with the PUT request. Products that are not specified in the PUT request will be removed from the order. The same applies to product option variants.
{
"total": "100"
"user_data": {
"email": "[email protected]",
"b_firstname": "John",
"b_lastname": "Doe",
"s_firstname": "John",
"s_lastname": "Doe"
}
}
This request:
Note
This won’t change the name or email of the user—only the name and email on the order page will change.
Note
If you try to specify the total
and other parameters that can affect it (like discount
or subtotal_discount
) in the JSON at the same time, then total
will always take priority. You can specify total
, but not subtotal
in the JSON.
The order has been updated successfully: HTTP/1.1 200 OK and the order ID:
{
"order_id": "98"
}
The order couldn’t be updated: HTTP/1.1 400 Bad Request.
The order doesn’t exist: HTTP/1.1 404 Not Found.
To delete an order, send the DELETE request to /api/orders/<order_id>/
. For example:
DELETE /api/orders/98/
This request will delete an order with order_id=98
.
Questions & Feedback
Have any questions that weren't answered here? Need help with solving a problem in your online store? Want to report a bug in our software? Find out how to contact us.