EasyWebshop API documentation

This page is available in English only.

2022-09-24 - Please use the non-WWW version for API requests: https://easywebshop.com

This document describes how to connect to the EasyWebshop API and how to write your own apps. It is intended for a technical audience familiar with programming and network protocols.

EasyWebshop API V3

Feature overview

Technology overview

To retrieve and send data we use REST. The data is sent and received in JSON or XML format over HTTPS. The encoding used is UTF-8. For the implementation into an application the free cURL tool can be used.

This approach has a lot of advantages:

Useful links:

API vs API PUSH vs Apps

APIAPI PUSHApps
Use the API for creating a custom connection for a specific customer. Use the API PUSH for creating a custom connection for a specific customer. Use apps for creating a connection that all EasyWebshop merchants can install themselves.
Ideal for importing and exporting categories, products, orders and customers. Ideal for synchronizing stock or accepting customers in real-time. Ideal for PSPs, delivery services, installing widgets, comparison sites, POS and invoicing applications.
Authentication in the backend via the API module. Enter PUSH URL in API module. Authentication in the backend via Apps.

How to start?

  1. Use an existing shop or create a new shop
  2. Adjust the user level to Expert, at Settings > User experience level
  3. Relax! It's easier than it looks

API

Activate the EasyWebshop API at Settings > Modules > Easywebshop API using the activation code MODA.

You can create a separate API user at Settings > Modules > Administrator accounts. This improves security: the API user can only use the API and cannot log in into the shop management.

Test your XML code without using cURL.

Section
Request method
Segment
XML file

Please cache your data, limit the number of API requests and limit data transfers as much as possible. Only query or update what you need. Do not use polling, use our PUSH functions instead.

API PUSH

Enter the URL of your application at Settings > Modules > Easywebshop API. You can test your connection using the buttons New customer and New order.

Apps

Apps can bypass the API authentication if a merchant installs them. For this, you need an App key. Contact us to receive your personal app key.

API

Retrieving data

The default output format is XML. You can change this by adding the query string ?format=json. Add pretty=1 to format the JSON data with whitespaces for improved human readability. Remove this to save bandwidth in automated systems.

Retrieve all categories
https://easywebshop.com/api/categorylist
Retrieve all categories in human readable JSON format
https://easywebshop.com/api/categorylist?format=json&pretty=1
Retrieve a specific category
https://easywebshop.com/api/category/Cocktails
Retrieve the last 1000 products
https://easywebshop.com/api/productlist
Retrieve the last 1000 products, but skip the first 1000 products
https://easywebshop.com/api/productlist?offset=1000
Retrieve products of the last 24h
https://easywebshop.com/api/productlist/86400
Retrieve products within a category
https://easywebshop.com/api/productlist/Cocktails
Retrieve product using the product code
https://easywebshop.com/api/product/C001
Retrieve the last 100 orders
https://easywebshop.com/api/orderlist
Retrieve orders from the last 24h
https://easywebshop.com/api/orderlist/86400
Retrieve the last 100 orders, but skip the first 100 orders
https://easywebshop.com/api/orderlist?offset=100
Retrieve the last 100 customers
https://easywebshop.com/api/customerlist
Retrieve the last 10 customers
https://easywebshop.com/api/customerlist/10
Retrieve a specific customer
https://easywebshop.com/api/customer/email@address.com

Sending data

Importing products with cURL:
curl -X POST -u linktest@mailinator.com:linktest -d @products.xml https://easywebshop.com/api/product

Change the log in credentials and the file to be imported so it matches your data. The XML file products.xml should have the following layout:

If your import succeeded you will see 201 Created.

Up to 1000 products can be imported at once. This limit prevents overloading our servers. If you want to import more products, you can repeat the command once per minute.

Updating products with cURL:
curl -X PUT -u linktest@mailinator.com:linktest -d @update.xml https://easywebshop.com/api/product

Change the log in credentials and the file to be imported so it matches your data. The XML file update.xml should have the following layout:

Up to 5000 products can be updated at once. This limit prevents overloading our servers. If you want to update more products, you can repeat the command once per minute.

Updating product stock with cURL:
curl -X PUT -u linktest@mailinator.com:linktest -d @updatestock.xml https://easywebshop.com/api/product

If the product is sold out, change the product status to Sold Out.

Possible product statuses:

Adding or updating product photos with cURL:
curl -X PUT -u linktest@mailinator.com:linktest -d @uploadimage.xml https://easywebshop.com/api/productimage

The XML file uploadimage.xml must have the following layout:

In the XML file, the URL of the product images are included. The first image always is the main photo, the next four are sub photos. When a product photo already exists, it will be replaced automatically. The images are scaled proportionally according to the standard size or, if set, according to the dimensions defined in the high quality photo module. Up to 5 photos per product can be added. The maximum file size is 5MB per photo, the supported formats are .png, .jpg and .gif. If you want to add more product photos, you can repeat the command once per 15 seconds.

If the command succeeded you will see 200 OK.

Deleting products with cURL:
curl -X DELETE -u linktest@mailinator.com:linktest https://easywebshop.com/api/product/LA-B03

If the product is successfully deleted you will see 200 OK.

Updating orders with cURL:
curl -X PUT -u linktest@mailinator.com:linktest -d @updateorder.xml https://easywebshop.com/api/order

Possible order statuses:

Accepting or denying customers with cURL:
curl -X PUT -u linktest@mailinator.com:linktest -d @updatecustomer.xml https://easywebshop.com/api/customer

You can deny the customer by sending 1 in the XML file. To accept the customer, set 0 in the denied tag.

Deleting customers by e-mail address with cURL:
curl -X DELETE -u linktest@mailinator.com:linktest https://easywebshop.com/api/customer/buddy@mailinator.com

If the command succeeded you will see 200 OK.

API limits

To prevend excessive querying, the API will automatically respond slower when many queries are sent. There is a limit of 48 requests per 24 hours in order to prevent continues polling.

API PUSH

Order PUSHCustomer PUSH
Contains an XML file with all the data of the order, the purchased products and information about the customer. Contains an XML file with all the information about the customer.
Fires when a customer places an order in the shop and when an order is placed using the cash register. (POS) Fires when a customer confirms his or her account.

Apps

Apps live on their own server and thus have their own URL. They come in various types:

TypeDescription
dsDelivery service: for implementing connections to transport services.

This is how it works:

  1. The customer is on the checkout page and selects a shipping method. Because your app is connected to a shipping method, this triggers a popup with iframe within.
  2. The customers address data is sent to the page in the iframe. (Your app URL)
  3. In your app, the customer can choose a shipping method or select a pick-up point from a map.
  4. Your app sends the shipping method name, price, description and a logo to our confirmation URL.
  5. The data is added to the order and the customer gets a confirmation.
htmlProvide the HTML/Javascript code. The merchant can choose on which pages of the shop he or she wants to install this code. Basically the same as copy and paste, but more user friendly.
invoiceBasically the same as psp, but focussed on payment on invoice. The customer details can be retrieved using this type.
productfeedRetrieve product data, for example for use on comparison sites.
pspPayment Service Provider: the easy way to connect a PSP to EasyWebshop.

This is how it works:

The customer has placed an order in the shop, and is now on the page with the Pay now button. This button submits a HTML form.
  1. You receive the POST data from the previous page on your server. Using the order code (POST data) and your personal app key you can safely retrieve all the data of the order.
  2. You send the order data to the payment service provider.
  3. If the payment is executed successfully, the payment service provider requests the report url. The status of the order gets changed to Payment received.
  4. The customer is redirected to the payment ok or to the payment failed URL, depending on the success or failure of the payment. If multiple payment methods are set, the customer can choose another payment after a failed payment.

How to write an app

index.php
This is the main file where a visitor is redirected to.
easywebshop.php
This is a script provided by us containing the code to connect to our API. Change your app key in this file.
settings.xml
This XML file contains the name of your app, the URL to your server and 5 optional parameters. For example, the ID of the shop for connecting to the payment service provider.
report.php
Only for PSPs: this script is called in the background by the payment service provider. It changes the status of the order to Payment received.

Creating an install button

<a href="https://easywebshop.com/software/apps/?install=https://www.webshopdata.com/app/easywebshop-psp">Install app</a>

Change the URL in the example to the URL of your app. Our backend automatically reads your settings.xml file and asks the user to enter the necessary data.

Examples

Coding examples can explain our API better than words. Feel free to use them in your own project.

FunctionDownloadSize
APIeasywebshop-api.zip168KB
API PUSHeasywebshop-push.zip1.6KB
Appseasywebshop-app.zip175KB
Delivery serviceeasywebshop-deliveryservice.zip26.1KB
HTML5 Widgeteasywebshop-html.zip167KB