Getting started

To begin using the ShopWeDo REST API version 1.2, 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
}

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.

HOST https://api1.shopwedo.com/api

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.

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 is invalid.

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

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.

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

POST /createOrder

Creates a new order.
Not supported yet: Stock pocket system.
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

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

  email

 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

  email

 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.

Type
Property
Required?
Description

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

POST /getOrder

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

Request

Type
Property
Required?
Description

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.

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

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

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

POST /getOrders

Returns an list of orders.
Authentication required.

Request

Type
Property
Required?
Description

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.

Type
Property
Required?
Description

array

orders

 Required

An array of order objects

400 Bad request

The request was invalid or no orders found.

  Cancel order

POST /cancelOrder

Cancels an order by its unique ID.
Authentication required.

Request

Type
Property
Required?
Description

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

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.

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.

Type
Property
Required?
Description

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.

  Get/List inventory

POST /getInventory

Get a inventory list for one or more stock items, grouped by its barcode or reference.
Authentication required.

Request

Type
Property
Required?
Description

string

group_by

 Required

On what field should the list be grouped by: barcode or reference

string

barcode

Filter the list based on a barcode.

string

reference

Filter the list based on a reference.

integer

limit

Amount of items per response, limits and defaults to 1000.

integer

offset

The offset, starts from 0.

Example{
    "group_by": "reference"
}

Response

200 OK

An array with stock data is returned.

Type
Property
Required?
Description

string

barcode

 Required

Stock item's barcode.

string

reference

 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.

array

dimensions

 Required

The stock item's dimensions in mm: length, width and height.

integer

level

 Required

A sum of the current level of stock items that are currently in stock.

integer

atp

 Required

A sum of 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.

400 Bad request

The request was invalid or empty. You may be missing a required argument or provided bad data.

  Create provisioning

POST /createStockOrder

Creates a new stock provisioning. [New in version 1.2]
Authentication required.

Request

Type
Property
Required?
Description

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.

Type
Property
Required?
Description

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

POST /getStockOrders

List and filter stock provisionings.
Authentication required.

Request

Type
Property
Required?
Description

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

POST /getStockOrder

Returns a provisioning by its unique ID.
Authentication required.

Request

Type
Property
Required?
Description

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.

Type
Property
Required?
Description

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

POST /cancelStockOrder

Cancels a provisioning by its unique ID.
Authentication required.

Request

Type
Property
Required?
Description

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

POST /getReturns

Get one or more returns, starting with the most recent.
Authentication required.

Request

Type
Property
Required?
Description

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.

Type
Property
Required?
Description

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

POST /pudo

Retreive a list of availlable pickup points for a given address.
Authentication required.

Request

Type
Property
Required?
Description

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.

Type
Property
Required?
Description

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.