Storefront API Configurations - WEBSALE Dokumentation

The Configuration API provides platform- and subshop-specific settings that are relevant for the appearance and behavior of the storefront. Typical contents are global shop settings (e.g. ShopID, country lists, salutations), subshop-specific values (e.g. language, currency, price formatting), as well as tax-relevant parameters such as gross/net display or VAT context. A complete overview of all available configuration settings of the shop platform is described in the documentation Configuration.

Supported methods

List of all supported methods.

Command	Endpoints	GET	PUT	POST	DELETE
Query configured address lists	`config/adress_lists`
Query configured consent groups	`config/consent`
Query configured countries + ISO codes	`config/countries`
Query configured shop currencies	`config/currency`
Query configuration for direct orders	`config/directOrder`
Query active password rules of the shop	`config/password`
Query available payment methods	`config/paymentMethods`
Query configured salutations	`config/salutation`
Query available shipping methods	`config/shippingMethods`
Query configured titles for customers	`config/title`
Query the current subshop ID	`subshop/current`
Query available subshops	`subshop/list`
Query complete subshop URL	`subshop/url`

Methods for configuration

These methods can be used to provide central shop configurations for the storefront. They deliver all selection lists and master data needed to build forms and processes, including predefined selection fields for billing and delivery addresses, countries, currencies, salutations, and titles. In addition, checkout-specific settings such as available payment and shipping methods, direct order parameters (quick entry by item number), and password rules (length restrictions, additional checks) can be read out and directly considered in the UI. Via the consent configuration, consent groups and services (e.g. captcha, tracking, media, service emails) can be viewed together with the current consent status. This allows consent dialogs, privacy settings, and the loading of external services to be controlled.

GET config/addressLists

The following call returns the configured selection fields for billing and delivery addresses. It also notes which value is preselected by default. The configuration is done under general.addressListElements. It can be used to build address forms (dropdowns/radio buttons including preselection) in the account, checkout, and address management. Example call that returns all configured selection fields:

GET https://<your-shop>.de/api/v1/config/address_lists

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "bill": {
    "companyType": {
      "defaultValue": "1",
      "values": [
        { "name": "Private", "value": "1" },
        { "name": "Company",  "value": "2" }
      ]
    }
  },
  "delivery": {
    "addressType": {
      "defaultValue": "1",
      "values": [
        { "name": "Private",      "value": "1" },
        { "name": "Packstation", "value": "3" }
      ]
    }
  }
}

The following call returns the consent groups defined in the shop (e.g. captcha) including the services contained in them (e.g. Google reCAPTCHA). Each group and each service has, among other things, a label, an internal identifier, a description, and the current consent status. It can be used to build the consent dialog and privacy settings, display groups/services, read current consents, and pre-fill UI switches accordingly. It can also be used to ensure that embeds/trackers are only loaded after consent. Example call that loads all consent groups defined in the shop

GET https://<your-shop>.de/api/v1/config/consent

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "groups": [
    {
      "allowed": false,
      "description": "Are you even a human?",
      "label": "Captcha",
      "name": "captcha",
      "services": [
        {
          "allowed": false,
          "description": "Google will be happy to check whether you are a human or robot in exchange for your data.",
          "label": "Google reCAPTCHA v3",
          "name": "recaptchav3"
        },
        {
          "allowed": false,
          "description": "Are you a robot? If not, it won't be difficult.",
          "label": "Friendly Captcha V1",
          "name": "friendlyCaptchaV1"
        }
      ]
    },
    {
      "allowed": false,
      "description": "Media is dear to us!",
      "label": "Media",
      "name": "media",
      "services": [
        {
          "allowed": false,
          "description": "We have a video on YouTube about us that we would like to show you.",
          "label": "YouTube Videos",
          "name": "youtube"
        }
      ]
    },
    {
      "allowed": false,
      "description": "we offer various services",
      "label": "ShopService",
      "name": "shopService",
      "services": [
        {
          "allowed": false,
          "description": "Are you OK with receiving an email to rate orders?",
          "label": "Rate Reminder",
          "name": "ratereminder"
        }
      ]
    },
    {
      "allowed": false,
      "description": "",
      "label": "Tracking",
      "name": "tracking",
      "services": [
        { "allowed": false, "description": "", "label": "Econda Analytics", "name": "econda" },
        { "allowed": false, "description": "", "label": "Google Analytics", "name": "google" }
      ]
    }
  ],
  "services": [
    { "allowed": false, "description": "", "label": "Econda Analytics", "name": "econda" },
    { "allowed": false, "description": "Are you a robot? If not, it won't be difficult.", "label": "Friendly Captcha V1", "name": "friendlyCaptchaV1" },
    { "allowed": false, "description": "", "label": "Google Analytics", "name": "google" },
    { "allowed": false, "description": "Are you OK with receiving an email to rate orders?", "label": "Rate Reminder", "name": "ratereminder" },
    { "allowed": false, "description": "Google will be happy to check whether you are a human or robot in exchange for your data.", "label": "Google reCAPTCHA v3", "name": "recaptchav3" },
    { "allowed": false, "description": "We have a video on YouTube about us that we would like to show you.", "label": "YouTube Videos", "name": "youtube" }
  ]
}

GET config/countries

The following call returns the countries configured in the shop including their ISO codes and display names. It can be used to populate country dropdowns (address, checkout), for validations, as well as for filtering/controlling country-specific processes. Example call that lists all countries configured in the shop:

GET https://<your-shop>.de/api/v1/config/countries

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "items": [
    { "isoAlpha2": "DE", "isoAlpha3": "DEU", "isoNum": "276", "name": "Germany" },
    { "isoAlpha2": "AT", "isoAlpha3": "AUT", "isoNum": "040", "name": "Austria" },
    { "isoAlpha2": "CH", "isoAlpha3": "CHE", "isoNum": "756", "name": "Switzerland" },
    { "isoAlpha2": "BE", "isoAlpha3": "BEL", "isoNum": "056", "name": "Belgium" },
    { "isoAlpha2": "IT", "isoAlpha3": "ITA", "isoNum": "380", "name": "Italy" },
    { "isoAlpha2": "PL", "isoAlpha3": "POL", "isoNum": "616", "name": "Poland" },
    { "isoAlpha2": "NL", "isoAlpha3": "NLD", "isoNum": "528", "name": "Netherlands" }
  ]
}

GET config/currency

The following call returns the currency currently configured in the shop including ISO code, ISO number, and currency symbol. It can be used for price formatting, the display in the cart/checkout, and for validations (e.g. with vouchers or shipping costs).

GET https://<your-shop>.de/api/v1/config/currency

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "isoCode": "EUR",
  "isoNum": "978",
  "symbol": "€"
}

GET config/directOrder

The following call returns the shop configuration for direct order (quick entry by item number). For example, it defines how many display rows are shown initially, how an item number is structured (field/separator), and what limits apply. It can be used to build the direct order form. Example call that loads the shop configuration for direct order

GET https://<your-shop>.de/api/v1/config/directOrder

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "initialNumber": 5,
  "itemNumberFields": [
    { "name": "firstField",  "required": true,  "type": "field" },
    { "sign": "-",           "type": "separator" },
    { "name": "secondField", "required": false, "type": "field" }
  ],
  "maximalNumber": 1000,
  "refreshedNumber": 5
}

GET config/password

The following call returns the active password rules of the shop (e.g. minimum/maximum length, additional checks). These rules come from the configured validation services (Validation and check services). It can be used for display and validation in password forms (registration, change/reset password) so that the entries already meet the shop requirements on the client side.

GET https://<your-shop>.de/api/v1/config/password

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "checkLoginID": true,
  "checkOldPassword": true,
  "passwordChecks": {
    "maxLength": { "len": 15 },
    "minLength": { "len": 3 }
  }
}

GET config/paymentMethods

The following call returns the payment methods available in the shop as a list (each with a technical ID and display name). It can be used to populate the payment method selection in the checkout. Example call that lists all payment methods available in the shop

GET https://<your-shop>.de/api/v1/config/paymentMethods

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "items": [
    { "id": "applepay", "name": "Apple Pay" },
    { "id": "bill", "name": "Invoice" },
    { "id": "creditcard", "name": "Credit Card" },
    { "id": "googlepay", "name": "Google Pay" },
    { "id": "maxpayment", "name": "Max Invoice" },
    { "id": "minpayment", "name": "Min Invoice" },
    { "id": "paypalCheckout", "name": "PayPal Checkout" },
    { "id": "paypalCheckoutApplePay", "name": "PayPal Checkout (Apple Pay)" },
    { "id": "paypalCheckoutBanContact", "name": "PayPal Checkout (BanContact)" },
    { "id": "paypalCheckoutBlik", "name": "PayPal Checkout (Blik)" },
    { "id": "paypalCheckoutCreditCard", "name": "PayPal Checkout (Credit Card)" },
    { "id": "paypalCheckoutEps", "name": "PayPal Checkout (EPS)" },
    { "id": "paypalCheckoutGiroPay", "name": "PayPal Checkout (GiroPay)" },
    { "id": "paypalCheckoutGooglePay", "name": "PayPal Checkout (Google Pay)" },
    { "id": "paypalCheckoutIdeal", "name": "PayPal Checkout (Ideal)" },
    { "id": "paypalCheckoutInvoice", "name": "PayPal Checkout (Invoice)" },
    { "id": "paypalCheckoutMyBank", "name": "PayPal Checkout (MyBank)" },
    { "id": "paypalCheckoutPayLater", "name": "PayPal Checkout (PayLater)" },
    { "id": "paypalCheckoutPrzelewy24", "name": "PayPal Checkout (Przelewy24)" },
    { "id": "paypalCheckoutSepa", "name": "PayPal Checkout (SEPA)" },
    { "id": "paypalCheckoutSofort", "name": "PayPal Checkout (Sofort)" },
    { "id": "paypalPlus", "name": "PayPal Plus" },
    { "id": "prepayment", "name": "Prepayment" },
    { "id": "safepayment", "name": "Secure payment method" },
    { "id": "stripe", "name": "Stripe" },
    { "id": "twint", "name": "Twint" }
  ]
}

GET config/salutation

The following call returns the salutations configured in the shop (each with code and display text). It can be used to populate selection lists in forms. Example call that lists the salutations configured in the shop:

GET https://<your-shop>.de/api/v1/config/salutation

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "items": [
    { "code": "1", "text": "Mr." },
    { "code": "2", "text": "Mrs." },
    { "code": "3", "text": "Family" },
    { "code": "4", "text": "Company" }
  ]
}

GET config/shippingMethods

The following call returns all shipping methods available in the shop with technical ID, display name, and type. It can be used to populate the shipping method selection in the checkout or to display available delivery options on info pages. Example call that lists all shipping methods available in the shop:

GET https://<your-shop>.de/api/v1/config/shippingMethods

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "items": [
    { "id": "pickup",  "name": "Click & Collect",   "type": "pickup"   },
    { "id": "dhl",     "name": "DHL",               "type": "standard" },
    { "id": "digital", "name": "Digital shipping", "type": "standard" },
    { "id": "hermes",  "name": "Hermes",            "type": "standard" }
  ]
}

GET config/title

The following call returns the configured titles (e.g. academic titles) for the customer and address forms. It can be used to populate title selection lists in forms. Example call that lists all titles configured in the shop

GET https://<your-shop>.de/api/v1/config/title

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "items": [
    { "code": "1", "text": "" },
    { "code": "2", "text": "Dr." },
    { "code": "3", "text": "Prof." }
  ]
}

Methods for subshop configurations

With these methods, the configuration of the subshop can be managed in the storefront context. They determine the currently active subshop ID (e.g. for language or country), list all available subshops, and generate a complete target URL for a specified subshop.

GET subshop/current

The following call returns the current subshop ID to the calling storefront for reading out the active subshop for language-/country- or theme-specific contents, URLs, and configurations. Example call that returns the current subshop ID of the calling storefront

GET https://<your-shop>.de/api/v1/subshop/current

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "id": "deutsch"
}

GET subshop/list

The following call returns a list of all subshops available in the shop. It can be used to build language/country selections, to switch between subshops, or for routing/link building per subshop. Example call that returns a list of available subshops:

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

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "items": [
    "deutsch",
    "english"
  ]
}

GET subshop/url

The following call returns the complete shop URL for a specified subshop and optionally takes over additional parameters into the query. It can be used for language/country change or to generate links (including optional parameters). Example call that creates a link for the subshop with the ID <ID> and appends the additional parameters value1&param and value2.

GET https://<your-shop>.de/api/v1/subshop/url?subshopId=<ID>&param[key]=value

Parameter overview

Body parameters

Parameter	Type	Description
`subshopId`	string	ID of the target subshop (e.g. `english`)
`param[…]`	string	Example: `param[key1]=value1&param[key2]=value2`

Example response

{
  "url": "https://en.<your-shop>.com/?key=value&foo=bar"
}

​Supported methods

​Methods for configuration

​GET config/addressLists

​Parameter overview

​Example response

​GET config/consent

​Parameter overview

​Example response

​GET config/countries

​Parameter overview

​Example response

​GET config/currency

​Parameter overview

​Example response

​GET config/directOrder

​Parameter overview

​Example response

​GET config/password

​Parameter overview

​Example response

​GET config/paymentMethods

​Parameter overview

​Example response

​GET config/salutation

​Parameter overview

​Example response

​GET config/shippingMethods

​Parameter overview

​Example response

​GET config/title

​Parameter overview

​Example response

​Methods for subshop configurations

​GET subshop/current

​Parameter overview

​Example response

​GET subshop/list

​Parameter overview

​Example response

​GET subshop/url

​Parameter overview

​Body parameters

​Example response

Supported methods

Methods for configuration

GET config/addressLists

Parameter overview

Example response

GET config/consent

Parameter overview

Example response

GET config/countries

Parameter overview

Example response

GET config/currency

Parameter overview

Example response

GET config/directOrder

Parameter overview

Example response

GET config/password

Parameter overview

Example response

GET config/paymentMethods

Parameter overview

Example response

GET config/salutation

Parameter overview

Example response

GET config/shippingMethods

Parameter overview

Example response

GET config/title

Parameter overview

Example response

Methods for subshop configurations

GET subshop/current

Parameter overview

Example response

GET subshop/list

Parameter overview

Example response

GET subshop/url

Parameter overview

Body parameters

Example response