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
}
Notice
There is a new host. Please update your API connection before 1 April 2023. The old host will be shut down soon.
The supported PHP library via composer and Node.js package via nmp are also updated.
All requests use this host.
Rate Limit
There is currently a rate limit of 3 request per second. If you exceed this limit, your request will be declied and you will receive a 429 HTTP header response code.
PHP Library
The ShopWeDo PHP Library on Packagist.org:
https://packagist.org/packages/shopwedo/shopwedoapi
This library can be installed using composer:
composer require shopwedo/shopwedoapi
Node.js package
The ShopWeDo Node.js package on npmjs.com:
https://www.npmjs.com/package/@shopwedo/shopwedoapi
This package can be installed using nmp:
npm i @shopwedo/shopwedoapi
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.)
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
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
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
The receiver's phone number.
string
eori
The receiver's eori number, if other then VAT number.
string
sellervat
The sellers' VAT number, if other then VAT number of the ShopWeDo account owner.
string
sellereori
The sellers' eori number, if other then VAT number of the ShopWeDo account owner or sellervat.
object
shipping_method
The shipping method to use: ship (default), pickup, parcelshop, parcellocker.
string
shipping_company
The shipping company to use: bpost, postnl, dpd, dhl, dhlparcel, ... (mandatory if shipping_method is parcelshop or parcellocker)
string
shipping_parcelshop_id
If shipping_method is parcelshop of parcellocker, this is the parcelshop's of parcellocker's identifier ID/String (mandatory if shipping_method is parcelshop or parcellocker)
array
items
Required
A line for each unique item
object
[item]
Required
Each orderline represents an item object. At least one is required.
string
external_orderline_id
Your unique order line ID.
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
double
price
The price of a single item, VAT inclusive. Maximal 2 decimals. Mandatory for non EU shipments.
integer
vat
The VAT percentage. Mandatory for non EU shipments.
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)
array
attributes
Extra attributes / information uses for personalisation
integer
personalisation
Required
The value is always 1
string
code
Required
A unique code for this type of production which indicates the design. This code is upfront created by ShopWeDo.
string
text
Required
The text uses for the personalisation. Foreign characters / languases (Rusian, Chinese,...) and emoticons are not allowed
string
text2
or text3,text4,... Extra text attributes if needed.
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.
string
external_order_id
Required
Your unique order ID. Either one is required.
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
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
The receiver's phone number.
array|bool
shipping
A collection of shipments. Returns false if empty.
object
[shipment]
...
string
code
The tracking barcode of the shipment
string
provider
The shipping provider (carrier) used for the shipment
string
tracking_url
The URL to the tracking website of the shipping provider.
DateTime
timestamp
The timestamp when the shipping label is created.
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.
List/Get orders
Returns an list of orders.
Authentication required.
Request
integer
limit
Amount of items per response, limits and defaults to 25.
integer
offset
The offset, starts from 0.
string
status
Filter orders by status. Choose one of these: waiting_release, released, collected, shipped, ready_pickup, cancelled.
datetime
update_since
Receive only the orders that have an update since YYYY-MM-DD HH:MM:SS.
Response
200 OK
An array of order objects (see get order) is returned.
array
orders
Required
An array of order objects
400 Bad request
The request was invalid or no orders found.
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.
string
barcode
Filter the list of SKUs based on a barcode.
string
reference
Filter the list of SKUs based on a reference.
integer
limit
Amount of items per response, limits and defaults to 50.
integer
offset
The offset, starts from 0 (page=offset/limit).
datetime
update_since
Receive only the SKU's that have an update since YYYY-MM-DD HH:MM:SS.
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
barcode
Required
Stock item's barcode.
string
reference2
Required
Stock item's reference.
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
lot_number
Required
The LOT / batch / production number on the stock item, if registerd.
string
tht_alert
Required
The THT alert type on the stock item.
string
tht_minimum
Required
Shipable period before expiration (in days).
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
items
Required
A line for each unique item
object
[item]
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",
"items": [
{
"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
amount_to_putaway
After the amount was checked, this value shows how many items the warehouse still needs to put away. After the putaway is done (value 0), then the provisioning is completed.
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).
Get/List returns
Get one or more returns, starting with the most recent.
Authentication required.
Request
integer
limit
Amount of items per response, limits and defaults to 25.
integer
offset
The offset, starts from 0.
datetime
created_since
Receive only the returns that are created since YYYY-MM-DD HH:MM:SS.
Example{
"limit": 25
}Response
200 OK
An array with returns is returned.
integer
return_id
Required
The unique ID of the return
integer
order_id
Required
The unique ShopWeDo order ID.
string
external_order_id
the external order ID
string
external_order_reference
The external order reference.
datetime
created_at
Required
The timestamp when the return was created.
string
return_service
Required
The ShopWeDo return service used: swd = ShopWeDo decided; destroy = destroy (trash) all returned products; ship = Collect and return products to shop owner.
array
items
Required
A list of items that are returned
object
[item]
Required
Each item represents a returned product.
integer
sku
Required
Our SKU/Stock item's Unique ID
string
barcode
Required
The barcode of the product.
string
reference
Required
The reference of the product.
integer
amount_return
Required
The amount of products returned (and back on stock).
integer
amount_damaged
Required
The amount of products damaged (or in trash).
400 Bad request
The request was invalid or empty. You may be missing a required argument or provided bad data.
Get pickup points
Retreive a list of availlable pickup points for a given address.
Authentication required.
Request
object
address
Required
An object containing the receiver's address.
string
country
Required
The receiver's country ISO code in 2 characters.
string
zip
Required
The receiver's zip code.
string
city
Required
The receiver's city.
string
street
Required
The receiver's street name.
string
number
The receiver's house number.
Example{
"address": {
"country": "BE",
"zip": "2800",
"street": "Egide Walschaertsstraat",
"number": "22"
}
}Response
200 OK
An object with a list of available pickup points is returned.
object
address
An object containing the receiver's address.
string
country
The receiver's country ISO code in 2 characters.
string
zip
The receiver's zip code.
string
street
The receiver's street name.
string
number
The receiver's house number.
array
carriers
The carriers used in the list.
integer
count
The number of results returned.
array
results
The list of returned pickup points.
object
pickuppoint
The list of returned pickup points.
string
pugoDistance
Distance from address in KM.
string
pugoCarrier
Required
The carrier. It is used for the label creation while shipping the order. This is important to save when an order is created.
string
pugoType
Required
The type of the pickup location. This is either parcelshop of parcellocker. It is used for the label creation while shipping the order. This is important to save when an order is created, see shipping method.
string
pugoId
Required
The unique ID for this pickup point. It is used for the label creation while shipping the order. This is important to save when an order is created.
string
pugoName
The name of the pickup point.
object
pugoAddress
The address of the pickup point.
string
street
The street name of the pickup point.
string
number
The street number of the pickup point.
string
countryIso2
The country ISO code in 2 characters of the pickup point.
string
zip
The zip code of the pickup point.
string
city
The city of the pickup point.
string
pugoLongitude
The longitude of the pickup point. This can be used to show little map pointers on a map like Goolge Maps.
string
pugoLatitude
The latitude of the pickup point. This can be used to show little map pointers on a map like Goolge Maps.
array
pugoHours
A list of the business hours of the pickup point.
object
hour
An object for a specific day of the business hours of the pickup point.
string
weekday
The day of the week.
string
openMorning
The opening hour in the morning.
string
closeMorning
The closing hour in the morning. If there is no break, then this is the final closing hour in the evening.
string
openAfternoon
The opening hour in the afternoon. If empty, then there is no break.
string
closeAfternoon
The closing hour in the evening. If empty, then there is no break.