API

Request API access

  1. Request Sandbox account creation and API access by email at: dropshipment@vidaxl.com
  2. Retrieve your sandbox API key in My account 
  3. Build and test your integration application with sandbox credentials
  4. Once confirmed ready, your production account and API access will be granted

Introduction Request API access

Drop-shippers can use our order API to create order and retrieve real-time order information.

Production environment base url - https://b2b.vidaxl.com

Test environment base url - https://sandbox.b2b.vidaxl.com/

Available ordert status 

  • 1- Temporary (order placed, but not paid yet)
  • 2- Submitted (order paid)
  • 4- Being prepared (order acknowledged by VidaXL)
  • 5- Sent (order shipped and invoice sent)
  • 7- Cancelled
  • 8- Refunded 

Please schedule a get order call in order to retrieve the latest order status. When order status is 5, tracking number and tracking url will also be availbal

Error Codes

It happens often that seller encounters 422 error with various error messages. 

Please make sure:

  1. Make sure the product you're ordering is active, which means both price and stock exists in offer feed
  2. Only create orders with country code where you're allowed to dropship. (e.g. if your account is registered to dropship in GB, but you're creating an order with DE, you wil get error message "Could not create order")

Order API 

Note: Automatic payment of orders through the API is not available yet. New orders will remain unpaid and available for payment in Unsubmitted orders

Authentication

Authentication is HTTP Basic authentication with username equal to the customer's email and password the API token of the customer 

customer_id OR customer_email fields are not required in the request because they are set based on the authenticated user

Header

Content-Type: application/json

Methods

Description Create Order
Action POST
URL /api_customer/orders
Sample request parameters

{
   "customer_order_reference": 74160086,
   "comments_customer":"Please deliver asap",
   "addressbook":{
      "address":"Covent Garden",
      "address2":"100",
      "province": "",
      "city":"Utrecht",
      "postal_code":"NR33 7NL",
      "country":"GB",
      "name":"John Wall",
      "phone": "0684541247",
      "comments":""
   },
   "order_products":[
      {
         "product_code":"274181",
         "quantity":1,
         "addressbook":{
            "address":"Covent Garden",
            "address2":"15",
            "city":"Utrecht",
            "province": "",
            "postal_code":"NR33 7NL",
            "country":"GB",
            "name":"tomtop",
             "phone": "0684541247",
            "comments":""
         }
      }
     
   ]
}

 
Sample Successful Response
{
    "order": {
        "id": 70,
        "status_order_id": 1,
        "customer_id": 9,
        "invoice_no": null,
        "customer_reference_no": 123521478861,
        "comments_customer": "Please deliver asap",
        "comments_wholesaler": null,
        "shipping_way": null,
        "shipping_costs": "0.0",
        "date_estimated": null,
        "total_before_discount": "95.97",
        "discount_percentage": "0.0",
        "discount_comments": null,
        "discount_total": null,
        "gross_total": "95.97",
        "address": null,
        "address2": null,
        "city": null,
        "province": null,
        "country": null,
        "postal_code": null,
        "created_at": "2018-06-08T03:47:48.000-04:00",
        "updated_at": "2018-06-08T03:47:48.000-04:00",
        "addressbook_id": 99,
        "submitted_at": null,
        "customer_order_reference": "74160086",
        "total_before_vat": "95.97",
        "total_after_vat": "0.0",
        "vat_group_id": null,
        "total_products_before_discount": "95.97",
        "total_vat": "0.0",
        "total_products_before_vat": "95.97",
        "total_products_after_vat": "95.97",
        "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": 25,
        "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": "1.0",
        "payment_date": null,
        "total_weight": "0.0",
        "payment_requested": false,
        "total_dimension": "0.0",
        "coupon_amount": "0.0",
        "coupon_vat": "0.0",
        "custom_discount_amount": "0.0",
        "save_for_later": true,
        "integration_ref_status": null
    },
    "order_products": [
        {
            "id": 108,
            "order_id": 70,
            "product_id": 12646,
            "quantity": "1.0",
            "price": "95.97",
            "final_price": "95.97",
            "discount_percentage": "0.0",
            "vat_percentage": "0.0",
            "total_before_vat": "95.97",
            "comments_customer": null,
            "comments_wholesaler": null,
            "total_vat": "0.0",
            "total_after_vat": "95.97",
            "option_value_ids": null,
            "created_at": "2018-06-08T03:47:48.000-04:00",
            "updated_at": "2018-06-08T03:47:48.000-04:00",
            "option_values": {},
            "product_variant_id": 0,
            "has_custom_price": false,
            "addressbook_id": 100,
            "status_order_id": null
        }
    ]
}
		
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, phone, comments

phone numbers should always be provided. If there’s no phone number available, please fill in your company’s number 

Access your orders with URL: 
/api_customers/orders.json 

Additional formats supported for listing orders: 
XML, CSV (change URL to /api_customers/orders.xml OR /api_customers/orders.csv)

Description List orders with details
Action GET
URL /api_customer/orders
Sample request 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_gt_eq (date with format: YYYY-MM-DD) 
Submitted at exact date: submitted_at_casted_eq (date with format: YYYY-MM-DD)   


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":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",
	 "shipping_tracking":"#81891238", 
         "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":"",
	 "shipping_option_name":"Express delivery"
      } 
   } 
]
		

Field descriptions for Orders

Name Type Description
id string Order id
status_order_id integer Status of order
customer_id integer Id of customer
submitted_at datetime Date that the order was submitted by customer
comments_customer string VidaXL tracking portal url, you can follow your order products' journey here
address string -
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 -
discount_percentage decimal -
discount_total decimal -
total_products_before_vat decimal -
total_before_vat decimal -
total_vat decimal -
total_products_after_vat decimal -
gross_total decimal -
shipping_option_id integer -
shipping_option_name string (available when shipping_option_id is available) 
shipping_tracking string tracking number of order 
shipping_costs decimal -
extra_fields string - not supported by API
customer_email string -
customer_company string -
customer_name string -
customer_pricelist_id integer -
customer_phone string -
customer_reference_code string - VidaXL partner id 

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_name string Product name
product_code string Product code
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>
		

 

 

Carrier and shipping_option_id mapping

Carrier

shipping_option_id

Australia Post

19

Bartolini

16

DHL

23

Direct Freight Express

18

DPD

8

GLS

10

Kuene + Nagel

15

PostNL

7

Raben

22

Seur

13

UPS

14

Yodel

9