API Documentation for developers
Getting started
To begin using the ShopWeDo REST API version 1.2, 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.
403
Forbidden
The resource or action requested is not allowed, for the currently authenticated user.
404
Not Found
The requested resource can not be found.
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.
Example{
"shopid": 123456,
"timestamp": 1574354210,
"salt": "SALT",
"token": "TOKEN"
}Response
202 Accepted
401 application/json
The authentication you provided is invalid. An error message will be returned explaining what happened.
Example{
"error": "Oops!"
}Create order
Creates a new order.
Not supported yet: Stock pocket system.
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
The timestamp when your order was created. Format: YYYY-mm-dd H:i:s.
timestamp
updated_at
The timestamp when your order was last updated. Format: YYYY-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 line for each unique item
object
[item]
Required
Each orderline represents an item object. At least one is required.
string
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)
Example{
"external_order_id": "unique_identifier12345",
"external_order_reference": "SO12345",
"release": "y",
"shipping_address": {
"company": "ShopWeDo",
"street": "Egide Walschaertsstraat",
"number": 22,
"box": "CD",
"zip": 2800,
"city": "Mechelen",
"country_iso2": "BE",
"phone": "003215616500",
"email": "no-reply@shopwedo.com"
},
"items": [
{
"skuType": "sku",
"amount": 1
},
{
"skuType": "reference",
"sku": "IAMAREFERENCE",
"amount": 1,
"comment": "Identifying information can be put here."
},
{
"skuType": "barcode",
"sku": "586564661414",
"amount": 3
}
]
}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
Example{
"order_id": 123
}400 application/json
The request was invalid or empty. You may be missing a required argument or provided bad data.
Example{"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.
Authentication required.
Request
string
order_id
Required
The unique order number to be returned.
Example{
"order_id": 666666
}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 line for each unique item
object
[item]
Required
Each line represents a unique item.
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 | external_order_id
Required
The unique order number to be cancelled. (external_order_id: by your external identifier, as long as the order is created via the API and fulfilment has not started)
Example{
"order_id": 666666
}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/List 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).
Example{
"sku": 1234
}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.
Create provisioning
Creates a new stock provisioning. [New in version 1.2]
Authentication required.
Request
string
external_stockorder_id
Your own unique order identifier to identify API-created provisionings.
string
reference
Your provisioning reference/description, eg. PO-number
date
report_date
Required
The most probable delivery date. Format: YYYY-mm-dd
array
lines
Required
A line for each unique item
object
[line]
Required
Each provisioning line represents a unique SKU. At least one line is required.
string
external_stockorder_line_id
Your own unique line number to identify API-created provisionings.
string
skuType
Type of sku: sku (default), reference or barcode
If value not set, then the system will check for any of the following fields: "sku", "reference", "barcode", else it will check for the field that has been explicitly set here)
string|integer
sku
Our SKU/Stock item's Unique ID
string|integer
reference
The reference for a Stock item
string|integer
barcode
The barcode/ean for a Stock item
integer
amount
Required
Amount being delivered of this stock item
date
tht_date
Helpful when the THT/Expiry date is already known beforehand, when multiple Expiry dates: add multiple lines with the same SKU/reference/barcode.
date
lot_number
Helpful when the Lot number is already known beforehand, when multiple lot numbers: add multiple lines with the same SKU/reference/barcode.
Example{
"external_stockorder_id": "example_identifier12345",
"reference": "PO1551515265",
"report_date": "2021-01-01",
"lines": [
{
"sku": 1234,
"amount": 1
},
{
"reference": "sku1",
"amount": 1,
"tht_date": "2023-06-24"
},
{
"barcode": "586564661414",
"amount": 3
},
{
"external_stockorder_line_id": "example_line_151551515",
"sku": 12346,
"amount": 5,
"lot_number": "LOT141515"
}
]
}Response
201 application/json
A new stock provisioning is successfully created.
boolean
success
Wether the creation was succesful
integer
stockorder_id
The ShopWeDo provisioning ID is returned when it was successfully created
object
stockorder
The ShopWeDo provisioning data is also returned when it was successfully created
Example{"success": true,"stockorder_id": 123, "stockorder": {...}}400 application/json
The request was invalid or empty. You may be missing a required argument or provided bad data. See "error" for more information as of why the request failed.
Example{
"error": "An error message will be returned with more info."
}List provisionings
List and filter stock provisionings.
Authentication required.
Request
array
filter
Filter upon the following fields:
string
name
General search (matches with "stockorder_id","reference")
integer
warehouse
Filter on the Warehouse ID (default: 1 for ShopWeDo EW)
string
status
Filter by status (1/"new"; 10/"to_be_received"; 11/"received"; 20/"awaiting_feedback"; 30/"approved"; 31/"denied"; "finished" groups all in 20,30,31; default: "all")
integer
limit
Amount of items per response, limits and defaults to 50.
integer
offset
The offset, starts from 0 (page=offset/limit).
integer
page
When no offset given, then usage of "page" (min 1) is allowed. The offset will be calculated by the system.
string
include_lines
Will include the orderlines of the returned stock provisionings in the response. (expects value: y)
Example{"filter":["name":"PO666666"]}Get provisioning
Returns a provisioning by its unique ID.
Authentication required.
Request
string
stockorder_id
Required
The unique stockorder / stock provisioning to be returned
Example{
"stockorder_id": 666123
}Response
200 OK
An object with stockorder/stock provisioning data is returned.
integer
stockorder_id
The Unique ID of the stockorder/provisioning
string
external_stockorder_id
External stockorder identifier.
integer
status
The Unique ID of the parent-order
string
status_string
An english status translation of the current status, spaces are replaced by underscores.
DateTime
received_date
The timestamp when the stock provisioning was set to received (status 11).
Date
report_date
The date when the stockorder was reported to be delivered (Format: YYYY-mm-dd, or null)
DateTime
created_at
The timestamp when the stock provisioning was created.
DateTime
updated_at
The timestamp when the stock provisioning was last updated.
array
lines
object
[line]
integer
stockorder_line_id
Unique provisioning line ID
string
external_stockorder_line_id
External provisioning line identifier
integer
sku
The actual SKU
integer
amount
The amount to be delivered.
integer
check_amount
The amount that was checked to be delivered by the warehouse.
integer
tht_date
The THT/expiry date set for this provisioning line (Format: YYYY-mm-dd, or null)
string
lot_number
The lot number set for this provisioning line (Format: YYYY-mm-dd, or null)
DateTime
created_at
The timestamp when the stock provisioning line was created.
DateTime
update_at
The timestamp when the stock provisioning line was last updated.
Cancel provisioning
Cancels a provisioning by its unique ID.
Authentication required.
Request
string
stockorder_id | external_stockorder_id
Required
The unique order number to be cancelled. (external_stockorder_id: by your external identifier, as long as the stockorder is created via the API and processing has not started)
Example{
"stockorder_id": 666123
}Response
200 OK
The provisioning is successfully cancelled.
400 Bad request
The request was invalid or the provisioning was already received, cancelled or completed.
404 Not found
The provisioning was not found (for the current authentication).
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
Get products
DEPRECATED ENDPOINT
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, format: YYYY-mm-dd
date
end
Required
The end date of the promotion, 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
DEPRECATED ENDPOINT
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
AWATING DEPRECATION
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.