Edit this page on GitHub

REST API - Basics

Introduction

The following page of the documentation covers the REST API. By using the REST API, shop owners can grant access to almost all data stored in their shop to 3rd party applications. It also allows direct manipulation of the shop data, regardless of the application or system used.

Basic Settings

To enable access to the REST API, the shop owner must authorize one (or more) users in the Shopware backend.

Simply open the Shopware backend and open the User Administration window, under Settings. From the list of existing users displayed on this window, select Edit for the desired user and mark the enabled checkbox in the API Access section.

You will get a randomly generated API access key, which needs to be included in your API requests for authentication. After clicking Save, the changes will take effect. If the edited user is currently logged in, you might need to clear the backend cache, and then log out and log in for your changes to take effect.

List of API Resources

The API has multiple resources, each responsible for managing a specific data type. These resources can be found in the engine/Shopware/Controllers/Api/ directory of your Shopware installation. Each resource has a correspondent URI and supports a different set of operations.

To get more details about the data provided by each specified resource, click on its name.

Name Access URL GET GET (List) PUT PUT (Batch) POST DELETE DELETE (Batch)
Address /api/addresses Yes Yes Yes No Yes Yes No
Product /api/articles Yes Yes Yes Yes Yes Yes Yes
Cache /api/caches Yes Yes No No No Yes Yes
Categories /api/categories Yes Yes Yes No Yes Yes No
Countries /api/countries Yes Yes Yes No Yes Yes No
Customer /api/customers Yes Yes Yes No Yes Yes No
CustomerGroups /api/customerGroups Yes Yes Yes No Yes Yes No
GenerateProductImage /api/generateArticleImages No No Yes No No No No
Manufacturers /api/manufacturers Yes Yes Yes No Yes Yes No
Media /api/media Yes Yes No No Yes Yes No
Orders /api/orders Yes Yes Yes No Yes No No
PaymentMethods /api/paymentMethods Yes Yes Yes No Yes Yes No
PropertyGroups /api/propertyGroups Yes Yes Yes No Yes Yes No
Shops /api/shops Yes Yes Yes No Yes Yes No
Translations /api/translations No Yes Yes Yes Yes Yes Yes
Users /api/users Yes Yes Yes No Yes Yes No
Variants /api/variants Yes No Yes Yes Yes Yes Yes
Version /api/version Yes No No No No No No

Authentication

We currently support two authentication mechanisms:

  • Digest access authentication
  • HTTP Basic authentication (introduced with Shopware 5.3.2)

Digest access authentication

The Digest access authentication is based on a simple challenge-response paradigm. The Digest scheme challenges using a nonce value. A valid response contains a checksum (by default MD5) of the username, the password, the given nonce value, the HTTP method, and the requested URI.

This ensures, that the password is never sent as plain text.

You can find a detailed explanation of the digest access authentication here and here.

HTTP Basic authentication

To use the HTTP Basic authentication, you just have to set an Authorization header which looks like this:

Authorization: Basic c2hvcDp3YXJl

The Authorization header has to follow this scheme: 1. Combine username and password with a single colon (:). 2. Encode the string into an octet sequence (more info). 3. Encode the string with Base64. 4. Prepend the authorization method and a space to the encoded string.

Please be aware that the Basic authorisation provides no confidentiality protection for the transmitted credentials. Therefore, you should always use HTTPS when using Basic authentication.

The authentication methods are not exclusive, you can use both of them simultaneously!

Using the REST API in your own application

To connect to the REST API, you need a client application. As REST is widely used as an inter-application communication protocol, several client applications and integration libraries already exist, both free and commercially, for different platforms and languages.

The examples shown in this documentation will work with any HTTP-Client. There's a variety of command-line or GUI applications which can be used for testing, and the standard library of your programming language of choice most likely includes a compatible HTTP-Client as well.

Every example will be accompanied by a badge like this:

GET /api/articles/4

The first part shows the HTTP-request method and the second part shows the route.

Some requests come with a body containing additional data like product information, these will have a code section attached to them and look like this:

PUT /api/articles/4 
{
  "name": "New name"
}

Communicating with the API

Query encoding

It is important that, when communicating with the Shopware API, all transmitted queries are UTF8-encoded. The date must be in ISO 8601 format.

More info about ISO can be found here:

Date formatting in PHP

//Generate valid ISO-8601
$now = new DateTime();
$string = $now->format(DateTime::ISO8601);
var_dump($string);
// output e.G.:
string(24) "2012-06-13T09:34:09+0200"

//Parse ISO-8601 Date
$string = "2012-06-13T09:34:09+0200";
$dateTime = new DateTime($string);
var_dump($dateTime);

// output
object(DateTime)#65 (3) {
  ["date"]=>
  string(19) "2012-06-13 09:34:09"
  ["timezone_type"]=>
  int(1)
  ["timezone"]=>
  string(6) "+02:00"
}

Date formatting in JavaScript

// Generate valid ISO-8601
var date = new Date();
var string = date.toJSON();
console.log(string); // Output: 2012-06-13T07:32:25.706Z
// Parse ISO-8601 Date
var string = "2012-06-13T07:32:25.706Z"
var date = new Date(string);

Filter, Sort, Limit, Offset

Every API comes with a set of default parameters which can be used to modify the given result. All parameters can be combined in a single request.

Filter

Filtering a results can be done using the filter parameter in your request. The available properties can be extracted from the Shopware models below.

Each filter can have the following properties:

  • property (Required)
  • value (Required)
  • expression (Default: LIKE, available: all MySQL expressions)
  • operator (If set, concats the filter using OR instead of AND)

Example: Active articles with at least 1 pseudo sale

GET /api/articles 
{
    "filter": [
        {
            "property": "pseudoSales",
            "expression": ">=",
            "value": 1
        },
        {
            "property": "active",
            "value": 1
        }
    ]
}

Example: Active articles or articles containing "beach" in their name

GET /api/articles 
{
    "filter": [
        {
            "property": "name",
            "value": "%beach%",
            "operator": 1
        },
        {
            "property": "active",
            "value": 1
        }
    ]
}

Example: Orders from customer which email address is "test@example.com"

Keep in mind, that the related entity must be joined in the query builder.

GET /api/orders 
{
    "filter": [
        {
            "property": "customer.email",
            "value": "test@example.com"
        }
    ]
}

Sort

The sorting syntax nearly equals to the filter section above. It uses the sort parameter in the request.

Each sorting can have the following properties:

  • property (Required)
  • direction (Default: ASC)

Example: Sort by article name

GET /api/articles 
{
    "sort": [
        {
            "property": "name"
        }
    ]
}

Example: First, sort by order time and then by invoice amount in descending order

GET /api/orders 
{
    "sort": [
        {
            "property": "orderTime"
        },
        {
            "property": "invoiceAmount",
            "direction": "DESC"
        }
    ]
}

Limit / Offset

By default, Shopware uses a soft limit on the API with a value of 1000. If you need more than 1000 results, increase it to your needs. The limiting uses the parameter limit, the offset start.

Example: Retrieve the first 50 results

GET /api/orders 
{
  "limit": 50
}

Example: Retrieve 50 results, skipping the first 20

GET /api/orders 
{
  "limit": 50,
  "start": 20
}

Models

You can find a list of all models at the following page:

Top