Orders¶

List All Orders¶

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.

GET /api/orders/?items_per_page=2

{
  "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": "dsds@example.com",
    "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": "customer@example.com",
    "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"
 }
}

Get a Specific Order¶

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

Create 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.

  • amount*—the amount of this particular product that is being ordered.
  • product_options—an object (associative array) that describes the options and option variants of the product. Option ID serves as the key, and option variant serves as the value.

• 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@example.com",
    "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": ""
  }
  

  • email*—customer’s e-mail
  • b_firstname*—first name (billing address)
  • b_lastname*—last name (billing address)
  • b_address*—address (billing address)
  • b_city*—city (billing address)
  • b_state*—2-symbol state code (billing address)
  • b_country*—2-letter country code (billing address)
  • b_zipcode*—zip code (billing address)
  • b_phone*—phone number (billing address)
  • s_firstname*—first name (shipping address)
  • s_lastname*—last name (shipping address)
  • s_address*—address (shipping address)
  • s_city*—city (shipping address)
  • s_state*—2-symbol state code (shipping address)
  • s_country*—2-symbol country code (shipping address)
  • s_zipcode*—zip code (shipping address)
  • s_phone*—phone number (shipping address)

  Note

  You can view the available country and state codes in the Administration panel of your store under Administration → Shipping & Taxes → States.

{
  "user_id": "3",
  "shipping_id": "1",
  "payment_id": "2",
  "products": {
      "1": {
        "product_id": "12",
        "amount": "1"
       },
      "2": {
        "product_id": "13",
        "amount":"2"
      }
  }
}

{
 "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"
 }
}

{
 "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":"guest@example.com",
    "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"
 }
}

Update an Order¶

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.

{
 "status": "P",
 "notify_user": "1",
 "notify_department": "1",
 "notify_vendor": "1"
}

{
 "products": {
   "1": {
     "product_id": "12",
     "amount": "1"
   },
   "3": {
     "product_id": "241",
     "amount": "1",
      "product_options": {
         "12": "44",
         "13": "48"
      }
   }
 }
}

{
 "total": "100"
 "user_data": {
   "email": "customer@example.com",
   "b_firstname": "John",
   "b_lastname": "Doe",
   "s_firstname": "John",
   "s_lastname": "Doe"
 }
}

Delete an Order¶

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.