Getting started

To begin using the ShopWeDo REST API version 1.1, follow the steps below.

  1. Get your personal access ID and key at support@shopwedo.com.
  2. 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
}
HOST https://shopwedo.com/admin/api

All requests use this host.

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.

Code
Status
Description

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.

401

Unauthorized

The Authentication required you provided is invalid.

  Authentication

POST /authTest

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

Type
Property
Required?
Description

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

POST /createOrder

Creates a new order. [Beta]
Authentication required.

Request

Type
Property
Required?
Description

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

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

  email

 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

  email

 Required

The receiver's email address.

string

  phone

 Required

The receiver's phone number.

array

items

 Required

A box for each item

object

  [item]

 Required

Each orderline represents an item object. At least one is required.

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.

Type
Property
Required?
Description

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

POST /getOrder

Returns an order by its unique ID, includes shipping information. [Beta]
Authentication required.

Request

Type
Property
Required?
Description

string

order_id

 Required

The unique order number to be returned.

Response

200 OK

An array with order data is returned.

Type
Property
Required?
Description

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

  email

 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

  email

 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

comment

...

string

comment_packing

...

string

language

...

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

POST /cancelOrder

Cancels an order by its unique ID.
Authentication required.

Request

Type
Property
Required?
Description

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

POST /getStock

Get one or more stock items. [Beta]
Authentication required.

Request

Type
Property
Required?
Description

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.

Type
Property
Required?
Description

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

POST /getProducts

Webshop feature
Get one or more products.
Authentication required.

Request

Type
Property
Required?
Description

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.

Type
Property
Required?
Description

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

POST /getCategories

Webshop feature
Get one or more categories/collections.
Authentication required.

Request

Type
Property
Required?
Description

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.

Type
Property
Required?
Description

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

POST /getBlogPosts

Webshop feature
Get one or more blog posts.
Authentication required.

Request

Type
Property
Required?
Description

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.

Type
Property
Required?
Description

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

GET https://[shopwedo/startsendr].com/admin/shipper/add?ext=manual&...

[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

Type
Property
Required?
Description

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