API reference text snippets - WEBSALE Dokumentation

The /text endpoint provides an interface for managing text snippets in our shop system. You can define language-specific variables that are used within templates. Changes to these texts can conveniently be made via the admin interface or automatically via the API, without having to adapt the templates themselves. The interface also provides functions for retrieving, editing and deleting individual text snippets as well as publishing the changes.

Supported methods

List of all supported methods.

Command/Info	Endpoints	GET	PUT	POST	DELETE
Text snippets	text
Publish	text/publish

Data fields of a text snippet

Name	Type	Meaning
variable	String	Name of the text variable through which the content is referenced in the template.
translations	Object	Array of text snippet data
translations.id	String	Unique index of the text snippet in the database (sequential number).
translations.text	String	The actual content of the text snippet (e.g. a note or a heading).
translations.languageId	String	Language code (e.g. `DE`, `EN`) of the language this text snippet belongs to.
translations.author	Integer	ID of the user who last changed this entry.
translations.system	Boolean	Indicates whether the text snippet is provided by the system by default.
translations.used	Boolean	Set to `true` if the text snippet has been used in a template.
translations.changedAt	String	Time of the last change of the text snippet (ISO 8601 format, UTC).
translations.configReferences	Integer	Number of configuration references that point to this text snippet. If the value is greater than 0, the text snippet cannot be deleted.

Example

{
    "translations": {
        "DE": {
            "author": 3,
            "changedAt": "2025-04-01T14:23:00Z",
            "configReferences": 0,
            "id": "42",
            "languageId": "DE",
            "system": true,
            "text": "In den Warenkorb",
            "used": true
        },
        "EN": {
            "author": 3,
            "changedAt": "2025-04-01T14:23:00Z",
            "configReferences": 0,
            "id": "43",
            "languageId": "EN",
            "system": true,
            "text": "Add to cart",
            "used": true
        }
    },
    "variable": "button.addToCart"
}

Methods for text snippets

The methods documented here provide an interface for managing text snippets in the shop system. They let you load, create, update and delete variables that contain language-dependent texts — for example, for buttons, error messages or other UI elements. Each text snippet can be available in multiple languages. To use these methods, the corresponding permissions to read, write, create or delete text snippets must be available.

3.1 GET text

This method loads a list of all available text snippets including their translations. Each entry contains the associated variable and the existing language versions with additional meta information such as time of change and author. To use this endpoint, the corresponding permissions to read text snippets must be available.

Example

https://www.<your-shop>.de/admin/api/v1/text

Response

{
    "endReached": true,
    "items": [
        {
            "translations": {
                "DE": {
                    "author": 3,
                    "changedAt": "2025-04-01T14:23:00Z",
                    "configReferences": 0,
                    "id": "42",
                    "languageId": "DE",
                    "system": true,
                    "text": "In den Warenkorb",
                    "used": true
                },
                "EN": {
                    "author": 3,
                    "changedAt": "2025-04-01T14:23:00Z",
                    "configReferences": 0,
                    "id": "43",
                    "languageId": "EN",
                    "system": true,
                    "text": "Add to cart",
                    "used": true
                }
            },
            "variable": "button.addToCart"
        }
    ],
    "nextPageToken": "MTAw",
    "totalCount": 1
}

Filter fields

variable, text, author, system, used, changedAt

Sort fields

variable, text, languageId, author, system, used, changedAt

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read text snippets.
400 Bad Request	”invalidValue”
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:”.

GET text/authors

This method returns a list of user IDs that have edited at least one text snippet. The data can be used, for example, to filter or analyze author activity. To use this endpoint, the corresponding permissions to read text snippets must be available.

Example

https://www.<your-shop>.de/admin/api/v1/text/authors

Response

{
    "items": [
        {
            "author": "1"
        }
    ],
    "totalCount": 1
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read text snippets.

GET text/{id}

This method loads all translations of a specific text snippet, identified by the name of the variable. For each language a separate entry is returned with information such as text content, editor and time of change. To use this endpoint, the corresponding permissions to read text snippets must be available.

Example

https://www.<your-shop>.de/admin/api/v1/text/button.addToCart

Response

[
    {
        "author": 1,
        "changedAt": "2025-02-17T11:46:54.000Z",
        "configReferences": 0,
        "id": "39",
        "languageId": "DE",
        "system": false,
        "text": "In den Warenkorb",
        "used": true
    },
    {
        "author": 1,
        "changedAt": "2024-12-18T14:44:54.000Z",
        "configReferences": 0,
        "id": "40",
        "languageId": "EN",
        "system": false,
        "text": "Add to cart",
        "used": true
    }
]

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read text snippets.

POST text

This method can be used to create a new text variable with multiple language versions. You provide the variable name name and at least one language object containing language data.languageId and text data.text. The variable must be unique — an entry with the same name must not yet exist. To use this endpoint, the corresponding permissions to create text snippets must be available.

Example

https://www.<your-shop>.de/admin/api/v1/text

Request body

{
    "name": "button.addToCart",
    "data": [
        {
            "languageId": "DE",
            "text": "In den Warenkorb"
        },
        {
            "languageId": "EN",
            "text": "Add to cart"
        }
    ]
}

Response

[
    {
        "author": 1,
        "changedAt": "2025-02-17T11:46:54.000Z",
        "configReferences": 0,
        "id": "39",
        "languageId": "DE",
        "system": false,
        "text": "In den Warenkorb",
        "used": false
    },
    {
        "author": 1,
        "changedAt": "2025-02-17T11:46:54.000Z",
        "configReferences": 0,
        "id": "40",
        "languageId": "EN",
        "system": false,
        "text": "Add to cart",
        "used": false
    }
]

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create text snippets.
400 Bad Request		Request body could not be loaded or the variable could not be created.
400 Bad Request	”invalidValue”	`name` or `data.languageId` is an empty string, or a data element is not an object.
400 Bad Request	”invalidFormat”	`name`, `data.languageId` or `data.text` is not a string, or `data` is not an array.
400 Bad Request	”invalidCharacters”	The variable name contains invalid characters.
400 Bad Request	”missing”	`name`, `data`, `data.languageId` or `data.text` were not provided.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body or in a data element.
409 Conflict		A variable with the same name already exists.

POST text/{id}/duplicate

This method can be used to duplicate an existing text variable. All language versions and properties of the original variable are taken over. The name of the new variable is generated automatically by appending a number to the end of the original name. If the original name does not yet contain a number at the end, the digit 1 is added (e.g. “titel” becomes “titel1”). If the name already ends in a number, the system checks which name variants with this prefix already exist and uses the next free higher number. Example: if variables with the names “x1” to “x9” already exist, duplicating one of them creates “x10”. If, for example, “x4” is missing, “x4” is created instead. The new variable is unique and can be used or edited independently of the original variable. To use this endpoint, the corresponding permissions to create text snippets must be available.

Example

https://www.<your-shop>.de/admin/api/v1/text/button.addToCart/duplicate

Response

{
    "translations": {
        "DE": {
            "author": 1,
            "changedAt": "2025-02-17T11:46:54.000Z",
            "configReferences": 0,
            "id": "41",
            "languageId": "DE",
            "system": false,
            "text": "In den Warenkorb",
            "used": false
        },
        "EN": {
            "author": 1,
            "changedAt": "2025-02-17T11:46:54.000Z",
            "configReferences": 0,
            "id": "42",
            "languageId": "EN",
            "system": false,
            "text": "Add to cart",
            "used": false
        }
    },
    "variable": "button.addToCart1"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create text snippets.
404 Not Found		Variable with `variable`=`{id}` was not found.
503 Service Unavailable	”internalError”	Duplication failed.

PUT text/{id}

This method can be used to update existing text snippets of a variable or to rename the variable itself. It is possible to change translations for one or multiple languages — languages that are not specified remain unchanged. To use this endpoint, the corresponding permissions to write text snippets must be available.

Example

https://www.<your-shop>.de/admin/api/v1/text/button.addToCart

Request body

{
    "name": "button.addToCart",
    "data": [
        {
            "languageId": "EN",
            "text": "Buy now"
        }
    ]
}

Response

[
    {
        "author": 1,
        "changedAt": "2025-02-17T11:46:54.000Z",
        "configReferences": 0,
        "id": "39",
        "languageId": "DE",
        "system": false,
        "text": "In den Warenkorb",
        "used": false
    },
    {
        "author": 1,
        "changedAt": "2025-04-30T14:10:12.000Z",
        "configReferences": 0,
        "id": "40",
        "languageId": "EN",
        "system": false,
        "text": "Buy now",
        "used": false
    }
]

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write text snippets.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue”	`name` or `data.languageId` is an empty string, or a data element is not an object.
400 Bad Request	”invalidFormat”	`name`, `data.languageId` or `data.text` is not a string, or `data` is not an array.
400 Bad Request	”invalidCharacters”	The new variable name contains invalid characters.
400 Bad Request	”missing”	`name`, `data` or `data.languageId` were not provided.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body or in a data element.
404 Not Found		Variable with `variable`=`{id}` was not found.
409 Conflict		A variable with the new name already exists.

DELETE text/{id}

This method can be used to delete an existing text variable completely. This affects all associated translations in different languages.
To use this endpoint, the corresponding permissions to delete text snippets must be available.

Example

https://www.<your-shop>.de/admin/api/v1/text/button.addToCart

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete text snippets.
404 Not Found		Variable with `variable`=`{id}` was not found.
409 Conflict	”systemText”	System texts cannot be deleted.
409 Conflict	”textInUse”	The variable is still used in a configuration and cannot be deleted.

Methods for publishing

The following methods let you publish text snippets in the shop system. The system checks whether a publishing process is running or whether a new one can be started. To use these functions, the corresponding permissions to publish text snippets must be available.

GET text/publish

This method can be used to check whether a publishing process for text snippets is currently running. If no process is active, the result of the last compilation is additionally returned as success. The success field is only present if running has the value false. To query the status, the corresponding permissions to read text snippets must be available.

Example

https://www.<your-shop>.de/admin/api/v1/text/publish

Response

{
    "running": false,
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read text snippets.
503 Service Unavailable	”internalError”	Internal error while retrieving the compilation status.

POST text/publish

This method recompiles the shop’s templates with the most recently changed text snippets. To start this process, the required permissions to publish text snippets must be available.

Example

https://www.<your-shop>.de/admin/api/v1/text/publish

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to publish text snippets.
503 Service Unavailable		The compilation of the templates could not be started.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​Data fields of a text snippet

​Example

​Methods for text snippets

​3.1 GET text

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET text/authors

​Example

​Response

​Error codes

​GET text/{id}

​Example

​Response

​Error codes

​POST text

​Example

​Request body

​Response

​Error codes

​POST text/{id}/duplicate

​Example

​Response

​Error codes

​PUT text/{id}

​Example

​Request body

​Response

​Error codes

​DELETE text/{id}

​Example

​Response

​Error codes

​Methods for publishing

​GET text/publish

​Example

​Response

​Error codes

​POST text/publish

​Example

​Response

​Error codes

​Support

Supported methods

Data fields of a text snippet

Example

Methods for text snippets

3.1 GET text

Example

Response

Filter fields

Sort fields

Error codes

GET text/authors

Example

Response

Error codes

GET text/{id}

Example

Response

Error codes

POST text

Example

Request body

Response

Error codes

POST text/{id}/duplicate

Example

Response

Error codes

PUT text/{id}

Example

Request body

Response

Error codes

DELETE text/{id}

Example

Response

Error codes

Methods for publishing

GET text/publish

Example

Response

Error codes

POST text/publish

Example

Response

Error codes

Support