Skip to main content
The Storefront API Basics page describes the fundamental technical framework conditions for using the Storefront API. This includes, among other things, the base URL and versioning, request/response format (JSON), authentication, and general conventions such as headers, error codes, and paging.

​
Base URL

All Storefront API endpoints are called under the following URL: 
https://<your-shop>.de/api/v1/
This URL is the basis for all requests, e.g. 
GET https://<your-shop>.de/api/v1/config/address_lists

GET https://<your-shop>.de/api/v1/watchList/list

POST https://<your-shop>.de/api/v1/form/send
For your-shop.de, the domain of the WEBSALE server must be used. This is different from the main domain of the shop. Please clarify the domain with your WEBSALE contact and also note Section 5.

​
Authentication

Unlike the Admin Interface API, the Storefront API does not require a separate API authentication. Requests to the Storefront API always run in the context of the public shop. Individual endpoints may nevertheless require an active session, e.g. for functions related to the customer account. In these cases, access is not controlled via a separate API login, but via the existing session or the normal login in the frontend.

​
Session handling

For coherent actions in the shop (e.g. building a shopping cart, using a wish list, reading customer-dependent data), a session must be used. The session is the unique ID with which the shop assigns multiple requests to a common context and can thus recognize user-specific data (e.g. shopping cart content and customer assignment). Not all endpoints require an active session. However, sending a session along is allowed at any time and expressly recommended when multiple requests belong to a coherent usage context.

​
Create session

A new session is created via the following endpoint: 
POST https://<your-shop>.de/api/v1/session/create
The exact structure of the response is described in the endpoint documentation. The key point is that the response returns a session ID (e.g. as a field such as sessionId or similar) that is reused for further requests.

​
Passing the session in requests

So that the shop recognizes an existing session, the session ID is then sent along with all further requests in the HTTP header X-Session.

​
Example request (raw format)

GET /api/v1/products/12345 HTTP/1.1
Host: <your-shop>.de
X-Session: 0123456789abcdef

​
Example with curl

curl -X GET "https://<your-shop>.de/api/v1/products/12345" \
  -H "X-Session: 0123456789abcdef"
  • X-Session is the name of the custom header.
  • The header value is the previously generated session ID.
The session is never appended to the URL via query parameters (e.g. ?session=…), but is exclusively transmitted via the header. This way, the session ID stays out of URLs and browser histories and can be cleanly controlled via the request context.

​
Effects of the session

Whether a session is required or evaluated depends on the respective endpoint:
  • For purely public data (e.g. general product information), a request without a session may be possible.
  • If a valid session is sent along, endpoints can return user-specific information, e.g.:
    • customer-dependent prices,
    • already filled shopping carts,
    • customer account-dependent settings.
If an endpoint is called that requires a valid session or a logged-in customer account, a missing or invalid session may return an error (e.g. 401 Unauthorized or 403 Forbidden). The exact error handling is described in the section “Error handling”.

​
Error handling

In the Storefront API, errors are returned uniformly via HTTP status codes and a structured error response in JSON format.
  • The HTTP status code indicates whether a request was generally successful (2xx) or failed (4xx/5xx).
  • The error response in JSON format provides additional details that can be used to specifically evaluate and display errors in the frontend (e.g. incorrect parameters or functional errors during execution).
The error response structure described in this section applies to all Storefront API endpoints. Under the individual endpoints, only the respective specific functional error codes are documented.

​
HTTP status codes

The Storefront API uses the usual HTTP status codes. Typical examples:
  • 2xx – Success
    • 200 OK – Request successful, response contains data.
    • 201 Created – Resource was successfully created.
    • 204 No Content – Request successful, but no data is returned.
  • 4xx – Client-side errors
    • 400 Bad Request – Request is invalid, e.g. due to incorrect or missing parameters or functional errors.
    • 401 Unauthorized – Authentication is missing or invalid.
    • 403 Forbidden – Request is authenticated, but not authorized.
    • 404 Not Found – Resource or endpoint was not found.
  • 5xx – Server-side errors
    • 500 Internal Server Error – Unexpected error in the backend.
For all 4xx and 5xx responses, the Storefront API additionally provides an error object in JSON format (see Section 3.2).

​
Error response

All error messages are returned in JSON format. The response follows a uniform structure that makes it possible to systematically evaluate errors and prepare them for the frontend: 
{
    "error": "<error_code>",
    "detail": "<description>",
    "paramErrors": {
      "<parameter_name>": {
        "type": "<error_type>"
      }
    },
    "actionErrors": [
      {
         "code" : "<code>",
         "details" : {},
         "field" : "<field>",
         "subCode" : "",
         "text" : "<error_text>"
      }
   ]
  }

​
Parameter overview error response

ParameterTypeDescription
errorShort, technical error code at the top level describing the type of error (e.g. invalidParameters, actionFailed).
detailOptional short description of the error, e.g. for logging or technical evaluations.
paramErrorsObject with detail information about incorrect parameters. The keys correspond to the parameter names, the values are objects with further information on the respective error. The paramErrors field can be empty depending on the error type. See section Parameter error codes
actionErrorsList of functional errors that occurred during the execution of the actual action (e.g. “Review not allowed for this order”). Each entry contains, among other things: - code – technical error code that names the cause, - field – optionally the affected field, - text – meaningful error message for display in the frontend, - details / subCode – optional additional information. The actionErrors field can be empty depending on the error type. See section Action errors

​
Parameter error codes (paramErrors)

Parameter errors occur when a request is formally invalid, e.g. because a required field is missing or a value has the wrong format. In these cases, the API usually returns:
  • the HTTP status 400 Bad Request
  • the error object with
    • error = "invalidParameters"
    • one or more entries in paramErrors
The error codes used in paramErrors.<parameter_name>.type have the following meaning:
Error codeTypeDescription
unknownDataFieldAn unknown field was sent.
invalidFormatThe parameter has an invalid format, e.g. string instead of integer or a non-parsable JSON fragment.
invalidValueThe value of the parameter is invalid - e.g. outside the valid range.
invalidCombinationTwo or more parameters are mutually exclusive.
syntaxErrorThere is a syntax error in the parameter.
missingA required field is missing.
readonlyFieldAn attempt was made to write to a read-only field.
duplicateEntryA value that may occur only once was used multiple times.

​
Action errors (actionErrors)

“Action” refers to all API calls that change the “shop state” — that is, usually POST, PUT, or DELETE calls (e.g. add product to cart, create address, subscribe to newsletter, etc.). Pure read calls (e.g. loading products) are not “actions” and generally do not return these errors. Action errors occur when the request is formally correct (all parameters are valid), but the requested action still cannot be successfully carried out, e.g.
  • No further review may be created for an order
  • The specified product cannot be rated in this context
  • An action is not allowed for the current state (e.g. item no longer available, minimum quantity not met)
In these cases, a suitable HTTP status code (usually a 4xx code, often 400 Bad Request) is returned. The error object additionally contains:
  • a suitable value in the error field that describes the general error category, e.g. actionFailed,
  • one or more entries in actionErrors that describe the specific action error
    • code – technical error code (e.g. ratingNotAllowed, orderNotFound, cartProductNotAvailable),
    • field – optionally the affected field or entity (e.g. productId, cart),
    • text – meaningful error text that can be displayed directly in the frontend or localized,
    • details – optional object with additional information (e.g. affected IDs, available quantity),
    • subCode – optional sub-code for finer differentiation.

​
Example

A customer tries to add a product to the cart. The request is formally correct (all parameters present and in the correct format), but the product is no longer available. HTTP response → Status: 400 Bad Request Response body: 
{
  "error": "actionFailed",
  "detail": "Product cannot be added to cart.",
  "paramErrors": {},
  "actionErrors": [
    {
      "code": "cartProductNotAvailable",
      "details": {
        "productId": 12345,
        "requestedQuantity": 2,
        "availableQuantity": 0
      },
      "field": "productId",
      "subCode": "",
      "text": "The selected product is currently unavailable and cannot be added to the cart."
    }
  ]
}
From this response, it can be seen that:
  • The request is formally correct (paramErrors is empty).
  • The action (add product to cart) could not be carried out (error = "actionFailed").
  • The functional reason is the action error with
    • code = "cartProductNotAvailable",
    • an affected field field = "productId" and
    • a meaningful error text in text that can be displayed directly in the frontend.
The structure of the error response shown here is the same for all endpoints. Which specific action error codes (actionErrors[].code) can occur at an endpoint is documented at the respective endpoint.

​
Setting up the Storefront API-based storefront

When a WEBSALE shop is called via its domain (e.g. www.your-shop.de), the storefront is delivered and displayed by default via the WEBSALE template theme. If the storefront is to be operated instead based on the Storefront API (e.g. with your own frontend framework), corresponding settings are required so that this new storefront is delivered and used. Please speak with your WEBSALE contact to discuss the necessary settings in detail.