Orders [API]

Description Create Order
Action POST
URL <your URL here>/api/orders
Sample request parameters 
{"customer_id":2, "customer_order_reference":"B2C ORDER #99","comments_customer":"Please deliver asap","addressbook":{"address":"Covent Garden","country":"GB"}, "order_products":[{"product_code":"mst", "quantity":5,"addressbook":{"address":"5th Avenue","country":"US"}},
{"product_code":"bpd", "quantity":5,"addressbook":{"address":"5th Avenue","country":"US"}}, {"product_code": "bpd","quantity":10,"addressbook":{"name":"John Doe", "address":"Alton Rd","country":"US", "comments":"Call before arriving"}}]}
Sample Successful Response 
{"order":{"id":59,"status_order_id":2,"customer_id":1,"invoice_no":null,"customer_reference_no":null,"comments_customer":"Please deliver asap","comments_wholesaler":null,"shipping_way":null,"shipping_costs":"0.0","date_estimated":null,"total_before_discount":"190.0","discount_percentage":"0.0","discount_comments":null,"discount_total":null,"gross_total":"203.775","address":"Covent Garden","address2":null,"city":null,"province":null,"country":"GB","postal_code":null,"created_at":"2017-10-10T05:50:10.000Z","updated_at":"2017-10-10T05:50:11.000Z","addressbook_id":7,"submitted_at":"2017-10-10T05:50:11.000Z","customer_order_reference":"B2C ORDER #99","total_before_vat":"190.0","total_after_vat":"0.0","vat_group_id":1,"total_products_before_discount":"190.0","total_vat":"0.0","total_products_before_vat":"190.0","total_products_after_vat":"203.775","total_shipping_after_vat":"0.0","sales_rep_id":null,"sales_rep_commission":"0.0","extra_fields":{},"submitted_by":{},"submitted_by_class":null,"integration_ref":null,"payment_way_id":null,"payment_ip":null,"payment_token":null,"payment_payer_id":null,"paid_amount":"0.0","is_paid":false,"shipping_option_id":null,"total_m3":"0.0","request_delivery_at":null,"pricelist_id":1,"shipping_tracking":null,"coupon_id":null,"brightpearl_sales_order_id":null,"cc_first_name":null,"cc_last_name":null,"cc_city":null,"cc_province":null,"cc_postal_code":null,"cc_country":null,"cc_address":null,"total_quantity":"20.0","payment_date":null,"total_weight":"0.0"},"order_products":[{"id":77,"order_id":59,"product_id":1,"quantity":"5.0","price":"9.5","final_price":"9.5","discount_percentage":"0.0","vat_percentage":"7.25","total_before_vat":"47.5","comments_customer":null,"comments_wholesaler":null,"total_vat":"3.4438","total_after_vat":"50.9438","option_value_ids":null,"created_at":"2017-10-10T05:50:10.000Z","updated_at":"2017-10-10T05:50:11.000Z","option_values":{},"product_variant_id":null,"has_custom_price":false,"addressbook_id":8},{"id":78,"order_id":59,"product_id":8,"quantity":"5.0","price":"9.5","final_price":"9.5","discount_percentage":"0.0","vat_percentage":"7.25","total_before_vat":"47.5","comments_customer":null,"comments_wholesaler":null,"total_vat":"3.4438","total_after_vat":"50.9438","option_value_ids":null,"created_at":"2017-10-10T05:50:10.000Z","updated_at":"2017-10-10T05:50:11.000Z","option_values":{},"product_variant_id":null,"has_custom_price":false,"addressbook_id":8},{"id":79,"order_id":59,"product_id":8,"quantity":"10.0","price":"9.5","final_price":"9.5","discount_percentage":"0.0","vat_percentage":"7.25","total_before_vat":"95.0","comments_customer":null,"comments_wholesaler":null,"total_vat":"6.8875","total_after_vat":"101.8875","option_value_ids":null,"created_at":"2017-10-10T05:50:11.000Z","updated_at":"2017-10-10T05:50:11.000Z","option_values":{},"product_variant_id":null,"has_custom_price":false,"addressbook_id":9}]}
Fields customer_id OR customer_email
(optional) addressbook_id OR addressbook with the following fields: address, address2, province, country, postal_code, name, comments
(optional) customer_order_reference
(optional) comments_customer
order_products (Array)
product_id OR product_code
quantity
(optional) addressbook_id OR addressbook with the following fields: address, address2, province, country, postal_code, name, comments



Authentication is HTTP Basic authentication with username equal to the customer's email and password the API token of the customer (which is generated in the backend and can be viewed by the customer afterwards)customer_id OR customer_email fields are not required in the request because they are set based on the authenticated user

Description Update Order Status
Action PATCH
URL <your URL here>/api/orders/<order id>/change_status
Sample request parameters 
{"status_order_id":3}
Sample Successful Response 
{"status":200,"message":"The order status is updated"}
Available parameters

status_order_id
notify (optional, set to 1 if you want to send an email to the customer)

Description Update Integration Ref

PATCH
URL <your URL here>/api/orders/<order id>/set_integration_ref
Sample request parameters 
{"integration_ref":"BB-0123"}
Sample Successful Response 
{"status":200,"message":"The order integration ref is updated"}

Description Update Tracking Number
Action PATCH
URL <your URL here>/api/orders/<order id>/set_shipping_tracking
Sample request parameters 
{"shipping_tracking":"GB-ANG-1293910"}
Sample Successful Response 
{"status":200,"message":"The tracking nunmber was updated"}
Available parameters
shipping_tracking
shipping_option_id (optional)
status_order_id (optional)
comments_wholesaler (optional)
notify (optional, set to 1 if you want to send an email to the customer)



Description Set/Update order admin extra field(s)
Action POST
URL <your URL here>/api/orders/<order id>/set_admin_fields
Sample request parameters
 


{
  "Order admin extra field name 1": "Your value here",
  "Order admin extra field name 2": "Your value here"
}
Sample Successful Response
 
{
  "status":200,
  "message":"Order admin fields updated"
}


List Orders with details

Access your orders with URL:
<your URL here>/api/orders.json

The latest 500 orders will be returned.

Additional formats supported for listing orders:
XML, CSV (change URL to <your URL here>/api/orders.xml OR <your URL here>/api/orders.csv accordingly)

Description List orders with details
Action GET
URL <your URL here>/api/orders
Sample url parameters 
id_eq=3
Available parameters By default, orders placed during the last 24h will be fetched if you do not include any parameters. If you need filtered results the following parameters are supported:

Order id: id_eq
Order status id: status_order_id_eq (integer)
Submitted at later than: submitted_at_gteq (date with format: YYYY-MM-DD)
Submitted at exact date: submitted_at_casted_eq (date with format: YYYY-MM-DD)  
Fetch multiple orders based on id: id_in[]=1&id_in[]=2&id_in[]=3
Fetch multiple orders based on status_order_id: status_order_id_in[]=1&status_order_id_in[]=2


Response

The structure of the response is as follows

orders
  order
    order-products
      order-product

Always the response will be an array of orders even if the result is one record.

Sample JSON Response
 
[
{
"order": {
      "id": "2",
      "status_order_id": 5,
      "status_order_name": "Sent",
      "customer_id": 2,
      "submitted_at": "2019-06-01T22:32:27.000-04:00",
      "comments_customer": "",
      "comments_wholesaler": "",
      "address": "4290 Payne Ave. Apt 10",
      "address2": "",
      "city": "San Jose",
      "province": "OR",
      "country": "US",
      "postal_code": "95117",
      "customer_order_reference": "",
      "shipping_option_id": null,
      "shipping_costs": "0.0",
      "shipping_tracking": null,
      "total_products_before_discount": "2000.0",
      "discount_percentage": "0.0",
      "discount_total": null,
      "total_products_before_vat": "2000.0",
      "total_before_vat": "2000.0",
      "total_vat": "0.0",
      "total_products_after_vat": "2170.0",
      "gross_total": "2170.0",
      "extra_fields": {},
      "request_delivery_at": null,
      "integration_ref": null,
      "payment_token": null,
      "deleted_at": null,
      "order_products": [
        {
          "order_product": {
            "id": 2,
            "order_id": 2,
            "product_id": 6,
            "quantity": "200.0",
            "price": "10.0",
            "final_price": "10.0",
            "discount_percentage": "0.0",
            "vat_percentage": "8.5",
            "total_before_vat": "2000.0",
            "total_vat": "170.0",
            "total_after_vat": "2170.0",
            "status_order_id": null,
            "status_order_name": "",
            "product_variant_code": "CFB - M",
            "product_name": "Coffee Beans",
            "product_code": "CFB"
          }
        }
      ],
      "customer_email": "delistraty1@gmail.com",
      "customer_company": "Santa Clara Company",
      "customer_name": "Joe",
      "customer_pricelist_id": 1,
      "customer_phone": "",
      "customer_reference_code": "",
      "addressbook_reference_code": null,
      "addressbook_type": "main",
      "addressbook_company_name": null,
      "addressbook_name": null,
      "addressbook_phone": null,
      "currency": "USD"
    }
}
]


Field descriptions for Orders

Name Type Description
id string Order id
status_order_id integer Status of order
status_order_name string Name of status
customer_id integer Id of customer
submitted_at datetime Date that the order was submitted by customer
comments_customer string Comments for order by customer
address string Address details of the order's customer
city string -
province string -
country string -
postal_code string -
customer_order_reference string Order reference by customer (eg purchase order no)
total_products_before_discount decimal Total of products before discount and VAT
discount_percentage decimal Discount percentage (if applicable)
discount_total decimal Discount total (if applicable)
total_products_before_vat decimal Total of products before VAT
total_before_vat decimal Same as total_products_before_vat
total_vat decimal VAT value
total_products_after_vat decimal Total of products including VAT calculation
gross_total decimal Total of the order including VAT and discounts if applicable
shipping_option_id integer Internal id of shipping carrier
shipping_option_name string Shipping carrier (available when shipping_option_id is available)
shipping_tracking string Tracking number of order
shipping_costs decimal Shipping costs
extra_fields string Extra fields as key value pairs, eg. extra_fields: { "key1": "value1", "key2", "value2" }
customer_email string -
customer_company string -
customer_name string -
customer_pricelist_id integer -
customer_phone string -
customer_reference_code string - not supported by API
payment_token string Payment token (eg from Paypal or Stripe)
payment_option_name string Which method did the customer use to pay
deleted_at


Field descriptions for Order Products

Name Type Description
id string Id of record
order_id integer Id of order
product_id integer Id of product
quantity decimal Quantity ordered
price decimal Price (not including discounts)
final_price decimal Price (including discounts if applicable)
discount_percentage decimal Discount percentage
vat_percentage decimal VAT percentage (if applicable)
total_before_vat decimal Line total before VAT
total_vat decimal Total VAT
total_after_vat decimal Line total after VAT
product_variant_code string Variant Code (if applicable)
product_name string Product name
product_code string Product code
estimated_delivery_date datetime Estimated delivery date for this order product
Sample XML Response
 
<?xml version="1.0" encoding="UTF-8"?> 
<orders type="array"> 
  <order> 
    <id type="integer">1</id> 
    <status-order-id type="integer">2</status-order-id> 
    <customer-id type="integer">1</customer-id> 
    <submitted-at type="dateTime">2016-04-07T14:31:23+01:00</submitted-at> 
    <comments-customer></comments-customer> 
    <address>My address</address> 
    <city>London</city> 
    <province></province> 
    <country>GB</country> 
    <postal-code>111222</postal-code> 
    <customer-order-reference></customer-order-reference> 
    <total-products-before-discount type="decimal">6.0</total-products-before-discount> 
    <discount-percentage type="decimal">0.0</discount-percentage> 
    <discount-total nil="true"/> 
    <total-products-before-vat type="decimal">6.0</total-products-before-vat> 
    <total-before-vat type="decimal">6.0</total-before-vat> 
    <total-vat type="decimal">0.0</total-vat> 
    <total-products-after-vat type="decimal">7.2</total-products-after-vat> 
    <gross-total type="decimal">7.2</gross-total> 
    <shipping-option-id type="integer">1</shipping-option-id> 
    <shipping-costs type="decimal">0.0</shipping-costs> 
    <extra-fields> 
    </extra-fields> 
    <order-products type="array"> 
      <order-product> 
        <id type="integer">1</id> 
        <order-id type="integer">1</order-id> 
        <product-id type="integer">4</product-id> 
        <quantity type="decimal">2.0</quantity> 
        <price type="decimal">3.0</price> 
        <final-price type="decimal">3.0</final-price> 
        <discount-percentage type="decimal">0.0</discount-percentage> 
        <vat-percentage type="decimal">20.0</vat-percentage> 
        <total-before-vat type="decimal">6.0</total-before-vat> 
        <total-vat type="decimal">1.2</total-vat> 
        <total-after-vat type="decimal">7.2</total-after-vat> 
        <product-name>Green Valley 23d</product-name> 
        <product-code>52214G</product-code> 
      </order-product> 
    </order-products> 
    <customer-email>demo@b2bwave.com</customer-email> 
    <customer-company>Customer Company Ltd</customer-company> 
    <customer-name>Customer Name</customer-name> 
    <customer-pricelist-id type="integer">1</customer-pricelist-id> 
    <customer-phone>123123123</customer-phone> 
    <customer-reference-code></customer-reference-code> 
  </order> 
  <order> 
    <id type="integer">2</id> 
    <status-order-id type="integer">2</status-order-id> 
    <customer-id type="integer">2</customer-id> 
    <submitted-at type="dateTime">2016-04-07T14:36:04+01:00</submitted-at> 
    <comments-customer></comments-customer> 
    <address></address> 
    <city></city> 
    <province></province> 
    <country>GB</country> 
    <postal-code></postal-code> 
    <customer-order-reference></customer-order-reference> 
    <total-products-before-discount type="decimal">317.0</total-products-before-discount> 
    <discount-percentage type="decimal">0.0</discount-percentage> 
    <discount-total nil="true"/> 
    <total-products-before-vat type="decimal">317.0</total-products-before-vat> 
    <total-before-vat type="decimal">317.0</total-before-vat> 
    <total-vat type="decimal">0.0</total-vat> 
    <total-products-after-vat type="decimal">317.0</total-products-after-vat> 
    <gross-total type="decimal">317.0</gross-total> 
    <extra-fields> 
    </extra-fields> 
    <order-products type="array"> 
      <order-product> 
        <id type="integer">2</id> 
        <order-id type="integer">2</order-id> 
        <product-id type="integer">4</product-id> 
        <quantity type="decimal">99.0</quantity> 
        <price type="decimal">3.0</price> 
        <final-price type="decimal">3.0</final-price> 
        <discount-percentage type="decimal">0.0</discount-percentage> 
        <vat-percentage type="decimal">0.0</vat-percentage> 
        <total-before-vat type="decimal">297.0</total-before-vat> 
        <total-vat type="decimal">0.0</total-vat> 
        <total-after-vat type="decimal">297.0</total-after-vat> 
        <product-name>Green Valley 23d</product-name> 
        <product-code>52214G</product-code> 
      </order-product> 
      <order-product> 
        <id type="integer">3</id> 
        <order-id type="integer">2</order-id> 
        <product-id type="integer">1</product-id> 
        <quantity type="decimal">2.0</quantity> 
        <price type="decimal">10.0</price> 
        <final-price type="decimal">10.0</final-price> 
        <discount-percentage type="decimal">0.0</discount-percentage> 
        <vat-percentage type="decimal">0.0</vat-percentage> 
        <total-before-vat type="decimal">20.0</total-before-vat> 
        <total-vat type="decimal">0.0</total-vat> 
        <total-after-vat type="decimal">20.0</total-after-vat> 
        <product-name>Conical Red Pot 14x14x11H</product-name> 
        <product-code>0244014</product-code> 
      </order-product> 
    </order-products> 
    <customer-email>demo+2@b2bwave.com</customer-email> 
    <customer-company>Our Super Company Ltd</customer-company> 
    <customer-name>Mr Manager</customer-name> 
    <customer-pricelist-id type="integer">1</customer-pricelist-id> 
    <customer-phone></customer-phone> 
    <customer-reference-code></customer-reference-code> 
  </order> 
  <order> 
    <id type="integer">3</id> 
    <status-order-id type="integer">2</status-order-id> 
    <customer-id type="integer">2</customer-id> 
    <submitted-at type="dateTime">2016-04-07T15:12:07+01:00</submitted-at> 
    <comments-customer>test comments</comments-customer> 
    <address></address> 
    <city></city> 
    <province></province> 
    <country>GB</country> 
    <postal-code></postal-code> 
    <customer-order-reference>12345</customer-order-reference> 
    <total-products-before-discount type="decimal">67.0</total-products-before-discount> 
    <discount-percentage type="decimal">0.0</discount-percentage> 
    <discount-total nil="true"/> 
    <total-products-before-vat type="decimal">67.0</total-products-before-vat> 
    <total-before-vat type="decimal">67.0</total-before-vat> 
    <total-vat type="decimal">0.0</total-vat> 
    <total-products-after-vat type="decimal">67.0</total-products-after-vat> 
    <gross-total type="decimal">67.0</gross-total> 
    <extra-fields> 
    </extra-fields> 
    <order-products type="array"> 
      <order-product> 
        <id type="integer">4</id> 
        <order-id type="integer">3</order-id> 
        <product-id type="integer">5</product-id> 
        <quantity type="decimal">1.0</quantity> 
        <price type="decimal">8.0</price> 
        <final-price type="decimal">8.0</final-price> 
        <discount-percentage type="decimal">0.0</discount-percentage> 
        <vat-percentage type="decimal">0.0</vat-percentage> 
        <total-before-vat type="decimal">8.0</total-before-vat> 
        <total-vat type="decimal">0.0</total-vat> 
        <total-after-vat type="decimal">8.0</total-after-vat> 
        <product-name>Brown Pot</product-name> 
        <product-code>8053327</product-code> 
      </order-product> 
      <order-product> 
        <id type="integer">5</id> 
        <order-id type="integer">3</order-id> 
        <product-id type="integer">1</product-id> 
        <quantity type="decimal">2.0</quantity> 
        <price type="decimal">10.0</price> 
        <final-price type="decimal">10.0</final-price> 
        <discount-percentage type="decimal">0.0</discount-percentage> 
        <vat-percentage type="decimal">0.0</vat-percentage> 
        <total-before-vat type="decimal">20.0</total-before-vat> 
        <total-vat type="decimal">0.0</total-vat> 
        <total-after-vat type="decimal">20.0</total-after-vat> 
        <product-name>Conical Red Pot 14x14x11H</product-name> 
        <product-code>0244014</product-code> 
      </order-product> 
      <order-product> 
        <id type="integer">6</id> 
        <order-id type="integer">3</order-id> 
        <product-id type="integer">3</product-id> 
        <quantity type="decimal">3.0</quantity> 
        <price type="decimal">13.0</price> 
        <final-price type="decimal">13.0</final-price> 
        <discount-percentage type="decimal">0.0</discount-percentage> 
        <vat-percentage type="decimal">0.0</vat-percentage> 
        <total-before-vat type="decimal">39.0</total-before-vat> 
        <total-vat type="decimal">0.0</total-vat> 
        <total-after-vat type="decimal">39.0</total-after-vat> 
        <product-name>Square light green pot 9x9x10Υ</product-name> 
        <product-code>3702309</product-code> 
      </order-product> 
    </order-products> 
    <customer-email>demo+2@b2bwave.com</customer-email> 
    <customer-company>Our Super Company Ltd</customer-company> 
    <customer-name>Mr Manager</customer-name> 
    <customer-pricelist-id type="integer">1</customer-pricelist-id> 
    <customer-phone></customer-phone> 
    <customer-reference-code></customer-reference-code> 
  </order> 
</orders>

Order Products

Order products, define the products per order. Order products per order can be in the same way as orders are retrieved:

URL <your URL here>/api/orders
Sample request parameters 
{"id_eq":3}
Sample Successful Response 
[ 
   { 
      "order":{ 
         "id":1, 
         "status_order_id":2, 
         "customer_id":1, 
         "submitted_at":"2016-04-07T08:08:08.000Z", 
         "comments_customer":"", 
         "address":"My address", 
         "city":"London", 
         "province":"", 
         "country":"GB", 
         "postal_code":"111222", 
         "customer_order_reference":"", 
         "total_products_before_discount":"6.0", 
         "discount_percentage":"0.0", 
         "discount_total":null, 
         "total_products_before_vat":"6.0", 
         "total_before_vat":"6.0", 
         "total_vat":"0.0", 
         "total_products_after_vat":"7.2", 
         "gross_total":"7.2", 
         "shipping_option_id":1, 
         "shipping_costs":"0.0", 
         "extra_fields":{ 


         },
         "order_products":[ 
            { 
               "order_product":{ 
                  "id":1, 
                  "order_id":1, 
                  "product_id":4, 
                  "quantity":"2.0", 
                  "price":"3.0", 
                  "final_price":"3.0", 
                  "discount_percentage":"0.0", 
                  "vat_percentage":"20.0", 
                  "total_before_vat":"6.0", 
                  "total_vat":"1.2", 
                  "total_after_vat":"7.2", 
                  "product_name":"Green Valley 23d", 
                  "product_code":"52214G" 
               } 
            }
         ], 
         "customer_email":"demo@b2bwave.com", 
         "customer_company":"Customer Company Ltd", 
         "customer_name":"Customer Name", 
         "customer_pricelist_id":1, 
         "customer_phone":"123123123", 
         "customer_reference_code":"" 
      } 
   } 
]

Description Change Product Quantity on Order Products
Action PATCH
URL <your URL here>/api/orders/<order id>/change_product_quantity
Sample request parameters 
{"order_product_id":1194,"quantity":20,"note":"Order line notes"}

Or for overriding pricing rules:
{"order_product_id":1194,"quantity":20,"has_custom_price":1,"price":100,"note":"Order line notes"}
Sample Successful Response 
{"order_product":{"id":1197,"order_id":304,"product_id":3488,"quantity":10.0,"price":92.00,"final_price":92.00,"discount_percentage":0.0,"vat_percentage":0.0,"total_before_vat":920.0,"total_vat":0.0,"total_after_vat":920.0,"product_name":"Box of boxes","product_code":"BOX01"},"status":200}

Description Add Product to Order
Action PATCH
URL <your URL here>/api/orders/<order id>/add_product
Sample request 
{"product_id":12,"quantity":4,"note":"Order line notes"}

Or for overriding pricing rules: 

{"order_product_id":1194,"quantity":20,"has_custom_price":1,"price":100,"note":"Order line notes"}
Sample Successful Response 
{"order_product":{"id":1198,"order_id":304,"product_id":204,"quantity":6.0,"price":30.0,"final_price":30.0,"discount_percentage":0.0,"vat_percentage":0.0,"total_before_vat":180.0,"total_vat":0.0,"total_after_vat":180.0,"product_name":"Another Box of Boxes","product_code":"52214P"},"status":200}
Required fields product_id, quantity

Description Remove Product from Order
Action PATCH
URL <your URL here>/api/orders/<order id>/remove_product
Sample request 
{"order_product_id":1198}
Sample Successful Response 
{"status":200,"message":"The product was removed from the order"}
Required fields order_product_id

Note: Changing of product in an existing order_product is not possible. However, you can remove the existing order product record first, then add a new order product record with the desired product and the same quantity. 

Description Get Order Product Note
Action GET
URL <your URL here>/api/orders/<order id>/order_product_note?order_product_id=<order product id>
Sample request /api/orders/559/order_product_note?order_product_id=5412
Sample Successful Response 
{
  "order_product": {
    "id": 5412,
    "order_id": 559,
    "product_id": 3,
    "quantity": "30.0",
    "price": "3.0",
    "final_price": "2.55",
    "discount_percentage": "15.0",
    "vat_percentage": "25.0",
    "total_before_vat": "76.5",
    "comments_customer": null,
    "comments_wholesaler": null,
    "total_vat": "19.125",
    "total_after_vat": "95.625",
    "option_value_ids": null,
    "created_at": "2017-09-06T10:01:56.000Z",
    "updated_at": "2017-09-08T01:35:38.000Z",
    "option_values": {},
    "product_variant_id": null,
    "has_custom_price": false
  },
  "note": "hello"
}
Required fields order_product_id
Description Add message to Order
Action POST
URL <your URL here>/api/orders/<order id>/add_message
Sample request 
{"from_user":"demo@b2bwave.com","message_text":"This is a test message","notify":true}
Sample Successful Response 
{"status": 200, "message": "Message added to order" }
Required fields from_user, message_text
Notes Use "notify": true if you need a notification to be sent to the customer (email). If you don't need an email to be sent to the customer, then use "notify": false

Still need help? Contact Us Contact Us