API Documentation for developers
Getting started
To begin using the ShopWeDo REST API version 1.1, follow the steps below.
- Get your personal access ID and key at support@shopwedo.com.
- Read the authentication documentation to create an authentication token.
Any requests should always contain the property "auth".
For POST requests also include the property "data".
{
"auth": {}, // authentication-object (JSON)
"data": {} // data-object (JSON), explained per method on the left
}
All requests use this host.
PHP Library
There's also a PHP Library on Github made by an external party:
Github: josbeir/shopwedo-php-api
Note: This library is not supported by ShopWeDo
Support
If you need any assistance, feel free to contact us at support@shopwedo.com
Response codes
Following are the HTTP response codes our API may return.
200
OK
It worked!
201
Created
The creation was successfully. The body should contain response content.
202
Accepted
When using POST /authTest, this response code indicates that the auth_token is valid.
400
Bad request
The request was invalid or empty. You may be missing a required argument or provided bad data. An error message will be returned explaining what happened.
Authentication
Method for creating an authentication token in HMAC SHA-512.
The post is only for testing the auth creation.
A authentication token older then 15 minutes will be rejected.
Request
integer
shopid
Required
Your own shop ID
timestamp
timestamp
Required
The current Unix timestamp. A timestamp can not be older than 15 minutes and can not be in the future.
string
salt
Required
A unique string.
string
token
Required
A unique hash HMAC SHA-512 encrypted string of the concatenation of the shop ID, shop KEY, timestamp and salt.
Response
202 Accepted
401 application/json
The authentication you provided is invalid. An error message will be returned explaining what happened.
{"error": "Oops!"}
Create order
Creates a new order. [Beta]
Authentication required.
Request
string
external_order_id
Required
Your unique order number.
string
external_order_reference
Your order reference, eg. Invoice number
boolean
release
When not given, an order won't be automatically released.
When given and true-ish, the order will be checked and released when all needed stock is available, otherwise reserved.
(Currently: it'll be released, and put back to 'waiting for release' later on when a certain stock quantity is not available.)
timestamp
created_at
Required
The timestamp when your order was created. Format YYY-mm-dd H:i:s.
timestamp
updated_at
The timestamp when your order was last updated. Format YYY-mm-dd H:i:s.
string
language
An "ISO 639" (2 character length) value for language, eg. 'nl'. (Supported: 'en', 'nl', 'de', 'fr', rest will fallback on 'en' in the process, but will be saved.)
string
comment
A specific comment for the order. (Informational property)
string
comment_packing
A specific comment for the shipment process of an order. (Informational property)
object
billing_address
An object containing the buyer's address.
If not given, the shipping address will be used.
string
firstname
The receiver's first name.
string
lastname
The receiver's last name.
string
company
The receiver's company name.
string
vat
The receiver's VAT number.
string
street
Required
The receiver's street name.
string
number
Required
The receiver's house number.
string
box
The receiver's box number.
string
zip
Required
The receiver's zip code.
string
city
Required
The receiver's city.
string
country_iso2
Required
The receiver's country ISO code in 2 characters.
string
Required
The receiver's email address.
string
phone
Required
The receiver's phone number.
object
shipping_address
Required
An object containing the receiver's address.
string
firstname
The receiver's first name.
string
lastname
The receiver's last name.
string
company
The receiver's company name.
string
vat
The receiver's VAT number.
string
street
Required
The receiver's street name.
string
number
Required
The receiver's house number.
string
box
The receiver's box number.
string
zip
Required
The receiver's zip code.
string
city
Required
The receiver's city.
string
country_iso2
Required
The receiver's country ISO code in 2 characters.
string
Required
The receiver's email address.
string
phone
Required
The receiver's phone number.
object
shipping_method
The shipping method to use: ship (default), pickup, parcelshop.
string
shipping_company
The shipping company to use: bpost, postnl, dpd, dhl, dhlparcel, ... (mandatory if shipping_method is parcelshop)
string
shipping_parcelshop_id
If shipping_method is parcelshop, this is the parcelshop's identifier ID/String (mandatory if shipping_method is parcelshop)
array
items
Required
A box for each item
object
[item]
Required
Each orderline represents an item object. At least one is required.
integer
skuType
Required
Type of sku: sku (default), reference or barcode
string|integer
sku
Required
Our SKU/Stock item's Unique ID
integer
amount
Required
Amount ordered of this stock item
string
name
The name of the ordered product for this very orderline. (Informational property)
string
comment
A specific comment for this very orderline. (Informational property)
Response
201 application/json
A new order is successfully created.
integer
order_id
Required
The ShopWeDo order ID is returned when the order is created
{"order_id": 123}
400 application/json
The request was invalid or empty. You may be missing a required argument or provided bad data.
{"order_id": false,"error": "order_invalid_data|order_creation_failed|order_items_empty""errors": {An object of validation_errors will be returned here when error=order_invalid_data, grouped per field.}}
Get order
Returns an order by its unique ID, includes shipping information. [Beta]
Authentication required.
Request
string
order_id
Required
The unique order number to be returned.
Response
200 OK
An array with order data is returned.
integer
order_id
Required
The Unique ID of the order
integer
parent_order_id
The Unique ID of the parent-order
string
external_order_id
External order ID.
string
external_order_reference
External order reference.
integer
shop_id
Unique shop id (Owner)
integer|bool
app_id
The app id.
integer|bool
app_name
The app name.
integer|bool
warehouse_id
Warehouse location ID
DateTime
created_at
Created at...
integer
status
Current status of order
string
status_string
Current status, stringified.
integer|bool
customer_id
The customer that made the order, will return false when no customer was assigned.
string
payment_method
The payment method that's been used. (API orders will state "EXTERN")
DateTime|bool
paid_at
DateTime|bool
desired_delivery_date
The desired delivery date.
object
shipping_address
Required
An object containing the receiver's address.
string
firstname
The receiver's first name.
string
lastname
The receiver's last name.
string
company
The receiver's company name.
string
vat
The receiver's VAT number.
string
street
Required
The receiver's street name.
string
number
Required
The receiver's house number.
string
box
The receiver's box number.
string
zip
Required
The receiver's zip code.
string
city
Required
The receiver's city.
string
country_iso2
Required
The receiver's country ISO code in 2 characters.
string
Required
The receiver's email address.
string
phone
Required
The receiver's phone number.
object
billing_address
An object containing the buyer's address.
string
firstname
The receiver's first name.
string
lastname
The receiver's last name.
string
company
The receiver's company name.
string
vat
The receiver's VAT number.
string
street
Required
The receiver's street name.
string
number
Required
The receiver's house number.
string
box
The receiver's box number.
string
zip
Required
The receiver's zip code.
string
city
Required
The receiver's city.
string
country_iso2
Required
The receiver's country ISO code in 2 characters.
string
Required
The receiver's email address.
string
phone
Required
The receiver's phone number.
array|bool
shipping
A collection of shipments. Returns false if empty.
object
shipment
...
object
shipment
...
DateTime|bool
shipped_at
Returns DateTime object of last announced shipment date, returns false if there's no shipment.
string
language
An "ISO 639" (2 character length) value for language, eg. 'nl'. (Supported: 'en', 'nl', 'de', 'fr', rest will fallback on 'en' in the process, but will be saved.)
string
comment
A specific comment for the order. (Informational property)
string
comment_packing
A specific comment for the shipment process of an order. (Informational property)
array
items
Required
A box for each item
object
[item]
Required
Each orderline represents an item object.
integer
sku
Required
Our SKU/Stock item's Unique ID
integer
amount
Required
Amount ordered of this stock item
string
name
The name of the ordered product for this very orderline. (Informational property)
string
comment
A specific comment for this very orderline. (Informational property)
400 Bad request
The request was invalid, the order not found or not owned by your account.
Cancel order
Cancels an order by its unique ID.
Authentication required.
Request
string
order_id
Required
The unique order number to be cancelled.
Response
200 OK
The order is successfully cancelled.
400 Bad request
The request was invalid or the order fulfilment is started or fulfilment is done.
Get stock
Get one or more stock items. [Beta]
Authentication required.
Request
integer
sku
The ID of a specific stock item. If not given, all data wil be returned.
integer
limit
Amount of items per response, limits and defaults to 50.
integer
offset
The offset, starts from 0 (page=offset/limit).
Response
200 OK
An array with stock data is returned.
integer
sku
Required
The Unique ID/SKU of the stock item
string
reference
Required
Stock item's internal reference (Barcode or similar).
string
description
Required
The description given to the stock item.
integer
warehouse_id
Required
ID of the stock item's Warehouse location. (eg. 1 = ShopWeDo Mechelen, BE)
integer
weight
Required
The stock item's weight in grams.
integer
items_in_box
Required
The number of items that are stored per box in this stock item. (DEPRECATED, defaults to 1)
integer
level
Required
The current level of stock items that are currently in stock.
integer
atp
Required
The available level of stock items, calculated by subtracting the out-of-stock warning level and the level currently in an order that was released.
integer
status
Required
The current status ID of the stock item.
string
status_string
Required
An english status translation of the current status, spaces are replaced by underscores.
string
tht_alert
Required
The THT alert type on the stock item.
datetime|bool
tht_date
Required
The date set for THT on the stock item.
datetime|bool
last_update
Required
The last time the stock item has been updated.
datetime|bool
last_atp_update
Required
The last time the ATP of the stock item has been calculated.
400 Bad request
The request was invalid or empty. You may be missing a required argument or provided bad data.
Get products
Webshop feature
Get one or more products.
Authentication required.
Request
integer|array
product_id
The ID of a specific product or an array of IDs.
integer|array
category_id
The ID of a specific collection or an array of IDs.
integer
offset
The page offset, start from 0, limited by 100 items. If not given, all data wil be returned.
Response
200 OK
An array with product data is returned.
integer
product_id
Required
The ID of a product
integer
product_parent_id
Required
If the product is a child (variant), than the parent product ID is given.
integer
sku
Required
The ID of the connected inventory's item
object
name
Required
The name of th product in different languages
string
nl
Required
The name of th product in dutch
string
fr
Required
The name of th product in french
string
en
Required
The name of th product in english
string
de
Required
The name of th product in german
object
description
Required
The description of th product in different languages
string
nl
Required
The description of th product in dutch
string
fr
Required
The description of th product in french
string
en
Required
The description of th product in english
string
de
Required
The description of th product in german
double
price
Required
The price of the product ex VAT.
double
VAT
Required
The VAT of the product
array
promotions
If the product has promotions, it's given here.
object
promotion
Required
The promotion.
double
price
Required
The discount value.
date
start
Required
The start date of the promotion in format YYYY-mm-dd
date
end
Required
The end date of the promotion in format YYYY-mm-dd
integer
status
Required
The product's status. 1: online, 2: out-of-stock, 0: offline
object
extra_handling
If the product has a extra handling, it's given here.
double
price
Required
The extra handling value.
object
description
Required
The description of the axtra handling in different languages.
string
nl
Required
The description of the axtra handling in dutch.
string
fr
Required
The description of the axtra handling in french.
string
en
Required
The description of the axtra handling in english.
string
de
Required
The description of the axtra handling in german.
string
barcode
The barcode of the inverntory item.
integer
ATP
Required
the Available-To-Promise value of the inverntory item.
double
weight
The inverntory item's weigth in grams.
integer
sort
Required
The sort / order of the product.
boolean
is_featured
Required
Whether the product is a featured as a homepage product.
boolean
is_virtual
Required
Whether the product is a virtual product.
boolean
is_nostock
Required
Whether the product can be sold withoud stock.
array
images
Required
The product's images. The first in the array is the main image.
object
img
Required
Each image is represented as an object with information.
string
src
Required
The link to the image.
string
alt
Required
The alt text of the image.
integer
product_child_id
If the image is assined to a specific product's variant, its ID is given here.
array
categories
Required
The product's categories.
object
category
Required
Each category is represented as an object with information.
integer
id
Required
The ID of the category.
object
name
Required
The name of th category in different languages
string
nl
Required
The name of th category in dutch
string
fr
Required
The name of th category in french
string
en
Required
The name of th category in english
string
de
Required
The name of th category in german
array
childs
An array of the product IDs from the childs / variants of the product.
array
related_products
An array of the product IDs related to this product.
400 Bad request
The request was invalid or empty. You may be missing a required argument or provided bad data.
Get collections
Webshop feature
Get one or more categories/collections.
Authentication required.
Request
integer|array
category_id
The ID of a specific collection or an array of IDs.
integer
offset
The page offset, start from 0, limited by 100 items. If not given, all data wil be returned.
Response
200 OK
An array with categorie data is returned.
integer
category_id
Required
The ID of a collection
integer
category_parent_id
Required
If the collection is a child, than the parent category ID is given.
object
name
Required
The name in different languages
string
nl
Required
The name in dutch
string
fr
Required
The name in french
string
en
Required
The name in english
string
de
Required
The name in german
object
description
Required
The description in different languages
string
nl
Required
The description in dutch
string
fr
Required
The description in french
string
en
Required
The description in english
string
de
Required
The description in german
integer
sort
Required
The sort / order of the category.
object
images
Required
The category's images.
string
foreground|background|product
Required
The link to the image.
integer
status
Required
The product's status. 1: online, 2: out-of-stock, 0: offline
array
childs
An array of the child IDs.
400 Bad request
The request was invalid or empty. You may be missing a required argument or provided bad data.
Get blog posts
Webshop feature
Get one or more blog posts.
Authentication required.
Request
integer|array
post_id
The ID of a specific blog post or an array of IDs.
integer
offset
The page offset, start from 0, limited by 100 items. If not given, all data wil be returned.
Response
200 OK
An array with blog post data is returned.
integer
post_id
Required
The ID of a blog post
string
title
Required
The title of the blog post
string
content
Required
The HTML content of the blog post
string
language
Required
The language of the blog post
string
date
Required
The date of the blog post in format Y-m-d H:i:s
string
image
The link to the image.
integer
status
Required
The blog post's status. 1: online, 0: offline
400 Bad request
The request was invalid or empty. You may be missing a required argument or provided bad data.
Manual labels
[Legacy] URL with parameters to prefill the form.
API authentication is not required, but you should be logged in into the admin section.
Please visit our support section about supplying manual label information (NL).
Request
string
trackingReference
A custom reference for this shipment; eg. an order ID. Accepts: a-z, A-Z, 0-9, -, _
string
addressFirstname
The firstname of the reciever. Field is not mandatory, but one of fistname, lastname or company name should be filled in.
string
addressLastname
The lastname of the reciever. Field is not mandatory, but one of fistname, lastname or company name should be filled in.
string
addressCompany
The company's name of the reciever. Field is not mandatory, but one of fistname, lastname or company name should be filled in.
string
addressEmail
Required
The email address of the reciever.
string
addressPhone
The phone number of the reciever. Field is only mandatory non-EU countries.
string
addressStreet
Required
The street of the reciever.
string
addressNumber
Required
The house number of the reciever.
string
addressBox
The box number of the reciever.
string
addressZip
Required
The zip code of the reciever.
string
addressCity
Required
The city of the reciever.
string
addressCountry
Required
The country's ISO code of the reciever. Default: BE
string
addressLanguage
Required
The language of the reciever. Choose from: nl, fr, en or de. Default: nl