To the home page
Contact

Form Toolkit

Store API

The Form Toolkit is fully headless-compatible. Every storefront feature — submission, confirmation logic, validation — is reachable through the Shopware Store API.

This page is aimed at developers building their own front-ends, mobile apps or integrating third-party systems.

Base URL & headers

Header Value
Content-Type multipart/form-data (with file upload) or application/x-www-form-urlencoded
sw-access-key Storefront access key of the sales channel
sw-language-id Optional, language UUID-hex
sw-context-token Optional, for logged-in customers

Base URL: https://<shop>/store-api

Endpoint: submit form

POST /store-api/prems/form/submit

Body fields

Field Required Description
form_id yes UUID of the form
<identifier> per definition per form field the submitted value (key = technical name)
<identifier>[] per definition Checkbox groups send an array
shopware_basic_captcha_confirm per captcha config Basic Captcha response
g-recaptcha-response per captcha config reCAPTCHA token

Hidden inputs for the product inquiry:

Field Meaning
__prems_product_id Product UUID
__prems_product_number Product number
__prems_product_name Display name
__prems_product_price Formatted price
__prems_product_url Canonical URL

Response

On success (HTTP 200) the endpoint returns a JSON FormSubmitRouteResponse with the result:

{
    "result": {
        "entryId": "01H...HEX",
        "responseType": "success-notice",
        "responseMessage": "Thank you! Your message has been submitted.",
        "redirectUrl": null,
        "redirectDelay": null
    }
}

On validation errors (HTTP 400) you receive a Shopware-standard ConstraintViolationException:

{
    "errors": [
        {
            "code": "VIOLATION::IS_BLANK_ERROR",
            "status": "400",
            "title": "Constraint violation error",
            "detail": "This value should not be blank.",
            "source": { "pointer": "/firstName" },
            "meta": { "parameters": [] }
        }
    ]
}

On captcha failure (HTTP 403) Shopware Core returns a CaptchaException.

If the plugin is disabled (HTTP 403) or the form id is unknown (HTTP 404) a FormSubmitException is returned.

Loading a form definition

To build your own front-end you need the form definition (fields, order, required flags, options). Load it via the DAL search endpoint:

POST /store-api/search/prems-form

Body:

{
    "filter": [
        { "type": "equals", "field": "id", "value": "<formId>" },
        { "type": "equals", "field": "active", "value": true }
    ],
    "associations": {
        "fields": { "sort": [{ "field": "sortOrder" }] }
    }
}

The response contains the form with all fields, their translations and visibility conditions.

Entity aliases

Alias Content
prems_form Form
prems_form_field Single field / structure element
prems_form_field_translation Translatable properties per language
prems_form_entry Submission
prems_form_mail_route Mail route

Events (for custom backend extensions)

Event Class Triggered
prems_form.submitted Prems\Plugin\PremsForm\Core\Event\PremsFormSubmittedEvent after a successful submission (Store API included)

Hook into this event to trigger custom actions or forward data to external systems.

Cookie settings