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 order status 

Mapping ID Order 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, the tracking number and tracking URL will also be available
It happens often that seller encounters 422 error with various error messages. 

Carrier and shipping ID mapping

ID mapping  Carrier
19 AUSPOST
16 BARTOLINI
23 DHL
18 Direct Freight Express
8 DPD
10 GLS
15 K+N
7 PostNL
22 Raben
13 SEUR
14 UPS
9 YODEL

 

Error Codes

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 will get  an error message "Could not create order")

1. CREATE 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

Create Order

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

    {
       "customer_order_reference": 70000001,
       "comments_customer":"Please deliver asap",
       "addressbook":{
         "country":"FR"     },
       "order_products":[
          {
             "product_code":"274181",
             "quantity":1,
             "addressbook":{
                "address":"Covent Garden",
                "address2":"15",
                "city":"London",
                "province": "",
                "postal_code":"NR33 7NL",
                "country":"GB",
                "name":"Test Company",
                 "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,
            "shipping_service_code": null,
            "shipping_service_name": null,
            "integration_data": {},
            "estimated_delivery_at": null,
            "error_code": null,
            "notes": 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,
                "is_backorder": false,
                "estimated_delivery_at": null,
                "cost": "0.0",
                "estimated_dispatch_at": 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 

 

 

Request parameters

  • Name Type Description Required or optional? Rules
    customer_order_reference string Order reference by customer (eg purchase order no) Optional  
    comments_customer string Your comment(s) to VidaXL about this order Optional  
    product_code integer SKU code of a product Required  
    quantity integer Quantity of the product_code Required  
    address string Ship to address Required Max 30 char and atleast one number. If exceeds 30 char please fill in the rest at address2.
    address2 string Ship to additional address (as example: Building A) Optional  
    city string Ship to city Required  
    province string US/AU: Ship to state
    EU: Ship to province
    US/AU: Required
    EU: Optional
     
    postal_code string Ship to zip/postalcode Required  
    country string Ship to country Required  
    name string Ship to customers name Required  
    phone string Ship to customers phone Optional  
    comments string Comment(s) of your customer about this order Optional  

 

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

2. GET Order API

GET Customer Order Reference

GET https://b2b.vidaxl.com/api_customer/orders?customer_order_reference_eq=xxxx   (fill in reference instead of xxxx)
EXAMPLE (GET https://b2b.vidaxl.com/api_customer/orders?customer_order_reference_eq=99991111) results:
[
    {
    "order": 
        {
        "id": "B2B111",
        "status_order_id": 5,
        "status_order_name": "Sent",
        "customer_id": 1,
        "submitted_at": "2019-04-30T15:35:05.000+02:00",
        "comments_customer": "",
        "comments_wholesaler": null,
        "address": "Teststraat 10",
        "address2": "",
        "city": "Rotterdam",
        "province": "",
        "country": "NL",
        "postal_code": "9101AA",
        "customer_order_reference": "99991111",
        "shipping_option_id": null,
        "shipping_costs": "0.0",
        "shipping_tracking": null,
        "shipping_tracking_url": "",
        "shipping_tracking_urls_by_number": [],
        "total_products_before_discount": "2.0",
        "discount_percentage": "0.0",
        "discount_total": null,
        "total_products_before_vat": "2.0",
        "total_before_vat": "2.0",
        "total_vat": "0.0",
        "total_products_after_vat": "2.154",
        "gross_total": "3.6648",
        "extra_fields": {},
        "request_delivery_at": null,
        "integration_ref": null,
        "order_products": 
        [
            {
            "order_product": {
            "id": 1234,
            "order_id": 123,
            "product_id": 9999,
            "quantity": "1.0",
            "price": "2.0",
            "final_price": "2.0",
            "discount_percentage": "0.0",
            "vat_percentage": "7.7",
            "total_before_vat": "2.0",
            "total_vat": "0.154",
            "total_after_vat": "2.154",
            "status_order_id": null,
            "status_order_name": "",
            "estimated_delivery_date": null,
            "estimated_dispatch_date": null,
            "addressbook": {
            "reference_code": null,
            "name": "test",
            "address": "test",
            "address2": "",
            "city": "tes",
            "province": "tes",
            "country": "NL",
            "postal_code": "1234",
            "phone": "",
            "comments": null
            },
            "product_name": "Test product",
            "product_code": "123456"
            }
            }
        ],
    "customer_email": "examplemail@gmail.com",
    "customer_company": "Example-company",
    "customer_name": "Example name",
    "customer_phone": "1234568129",
    "customer_reference_code": "",
    "addressbook_reference_code": null
        }
    }

]

 

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

Additional formats supported for listing orders: 
XML, CSV (change URL to /api_customer/orders.xml OR /api_customer/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)   

     

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

     

     

     

‚ÄčThe structure of the response is as follows
Response

orders 
  order 
    order-products 
      order-product

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

3. GET Invoice API 

Authentication

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

Method 1: Get invoices *from date till today.

  • Description Get invoices *from date till today
    Action GET
    URL /api_customer/orders/documents?submitted_at_gteq=YYYYMMDD
    Sample response

    [
        {
            "id": 1,
            "documents": [
                {
                    "url": "https://b2b.vidaxl.com/uploads/orders/1/invoice/fs52324e-b97f-4b17-b7d6-921c943esde9/invoice.pdf",
                    "file_name": "invoice.pdf",
                    "description": "Invoice"
                }
            ]
        }
    ]

 

Method 2: Get invoices from past 4 days.

  • Description Get invoices from past 4 days
    Action GET
    URL /api_customer/orders/documents
    Sample response

    [
        {
            "id": 1,
            "documents": [
                {
                    "url": "https://b2b.vidaxl.com/uploads/orders/1/invoice/2ds43631a-1fb0-4d7c-8d20-81247d78e2c1/invoice.pdf",
                    "file_name": "invoice.pdf",
                    "description": "Invoice"
                }
            ]
        },
        {
            "id": 2,
            "documents": [
                {
                    "url": "https://b2b.vidaxl.com/uploads/orders/2/invoice/57465380-2940-46e7-bdab-cae73aed55ac/invoice.pdf",
                    "file_name": "invoice.pdf",
                    "description": "Invoice"
                }
            ]
        }

    ]

 

Method 3 Get invoice from sepcific order.

  • Description Get invoice from specific order
    Action GET
    URL /api_customer/orders/<order-id>/documents
    Sample response

    [
        {
            "id": 1,
            "documents": [
                {
                    "url": "https://b2b.vidaxl.com/uploads/orders/1/invoice/2ds43631a-1fb0-4d7c-8d20-81247d78e2c1/invoice.pdf",
                    "file_name": "invoice.pdf",
                    "description": "Invoice"
                }
            ]
        }
    ]

4. GET Product(s) API 

 

Authentication

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

Method 1: Get all products (that you are allowed to sell).

  • Description Get all products (that you are allowed to sell)
    Action GET
    URL /api_customer/products
    Sample response

    [
        {
            "id": 4,
            "name": "Intex 91507 Pool Cover Round 366 cm 28022",
            "code": "100058",
            "category_path": "Animals & Pet Supplies/Pet Supplies/Cat Supplies/Cat Furniture",
            "quantity": "0.0",
            "price": "75.00",
            "created_at": "2017-09-18T10:25:58.000+02:00",
            "updated_at": "2019-03-27T13:58:51.000+01:00"
        },
        {
            "id": 5,
            "name": "vidaXL Triangular Hammock for Hamsters",
            "code": "100074",
            "category_path": "Animals & Pet Supplies/Pet Supplies/Small Animal Supplies/Small Animal Habitat Accessories",
            "quantity": "0.0",
            "price": "4.90",
            "created_at": "2017-09-18T10:25:59.000+02:00",
            "updated_at": "2018-10-30T10:37:40.000+01:00"
        }
    ]

 

Method 2: Get a specific product.

  • Description Get a specific product.
    Action GET
    URL /api_customer/products?code_eq=XXXXX (fill at XXXXX the SKU of the product you are searching for) in this case we use 100058.
    Sample response

    [
        {
            "id": 4,
            "name": "Intex 91507 Pool Cover Round 366 cm 28022",
            "code": "100058",
            "category_path": "Animals & Pet Supplies/Pet Supplies/Cat Supplies/Cat Furniture",
            "quantity": "0.0",
            "price": "75.00",
            "created_at": "2017-09-18T10:25:58.000+02:00",
            "updated_at": "2019-03-27T13:58:51.000+01:00"
        }
    ]

Method 3: Get products in batches.

  • Description Get products in batches.
    Action GET
    URL
    /api_customer/products?limit=100&offset=0(from 0-100th product)

    /api_customer/products?limit=100&offset=101(from 101th to 200th product)

    /api_customer/products?limit=100&offset=201(from 201th to 300th product)
    Sample response

    [
        {
            "id": 4,
            "name": "Intex 91507 Pool Cover Round 366 cm 28022",
            "code": "100058",
            "category_path": "Animals & Pet Supplies/Pet Supplies/Cat Supplies/Cat Furniture",
            "quantity": "0.0",
            "price": "75.00",
            "created_at": "2017-09-18T10:25:58.000+02:00",
            "updated_at": "2019-03-27T13:58:51.000+01:00",


        "pagination": "{
            "offset": "6",
            "limit": "5",
            "total": "49996"
        }
    ]