Add a quote-request form

A contact or quote form is the first thing every shop wants. A "quote request" in this guide means a form submission that your sales team answers, not a quote in the Quotes App (the next section says when to use which). This guide takes one from nothing to a form on a storefront page that records each enquiry, tells the visitor what happened and hands the enquiry to the system your sales team works in. The form is built from a schema, so a new form is data on the platform and not a deploy of your Theme.

This is for the developer wiring the storefront side, together with whoever sets up the Forms App in Cockpit. You need a tenant with the Forms App installed, a storefront Theme that extends the base layer @revenexx/cover (Storefronts); custom-theme and cover-theme are two packages in the storefront layer repo that do, and the guide names which one it means where it matters, and an API key with the forms.* scopes (which scope covers which app). Step 5 also needs Integration Studio.

export REVENEXX_TENANT="<TENANT_SLUG>"
export REVENEXX_API_KEY="rvxk_..."

Forms App or Quotes App

The platform has two places a "quote request" can land, and they are not interchangeable.

This guide builds a Forms App form, because a form that asks "what do you need a price for?" has no positions to copy onto a quote and has to work for a visitor who has no account. When the buyer already has a cart you cannot order as it stands, use the quote path instead: Turn an accepted quote into an order starts with the request call. The two combine: a workflow in step 5 could turn a form that collects an article number and a quantity into a quote request, but this guide does not build that (not yet confirmed end to end, as of 2026-11).

How a submission travels

Both /api/forms/... routes are on your storefront's origin and ship in @revenexx/cover, so you write no server code for them. The gateway call happens inside them, with the key that never reaches the browser (The BFF pattern).

1. Create the form and publish it

A form is a name, a slug and a FormKit schema: a flat array of nodes. A node with a name collects one value and writes it under that name in the submission's data. A node with $el is plain content, such as a paragraph of text, and collects nothing.

Create it with POST /v1/forms; copy the id from the response, you need it as <FORM_ID> in the publish call below. Only name and slug are required. The slug is what the storefront looks the form up by, so choose it as carefully as a URL: lower-case letters, digits and inner hyphens, unique per tenant.

curl -s -X POST https://api.revenexx.com/v1/forms \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quote request",
    "slug": "quote-request",
    "lead_stage": "lead",
    "settings": {
      "submit_label": "Request a quote",
      "success_message": "Thanks. We answer quote requests within one working day.",
      "notify_email": "sales@example.com"
    },
    "definition": [
      { "$el": "p", "children": "Tell us what you need a price for." },
      { "$formkit": "text", "name": "company", "label": "Company", "validation": "required" },
      { "$formkit": "text", "name": "name", "label": "Your name", "validation": "required" },
      { "$formkit": "email", "name": "email", "label": "Email", "validation": "required|email" },
      { "$formkit": "tel", "name": "phone", "label": "Phone" },
      { "$formkit": "text", "name": "sku", "label": "Article number" },
      { "$formkit": "number", "name": "quantity", "label": "Quantity", "min": 1 },
      { "$formkit": "textarea", "name": "message", "label": "What do you need a price for?", "rows": 4, "validation": "required" },
      { "$formkit": "checkbox", "name": "privacy", "label": "I agree that my details are stored, saved as a contact and passed to our sales systems to answer this request.", "validation": "accepted" }
    ]
  }' | jq '{id, slug, status}'

{
  "id": "<FORM_ID>",
  "slug": "quote-request",
  "status": "draft"
}

Four things in that body are worth knowing:

• Input types are FormKit's. text, email, tel, textarea, number, select, checkbox, radio and date all work, and so do group and list. The storefront adds a datepicker input and the validation rules zip, companyName and phoneNumber. A $rxStep marker splits the array into the steps of a wizard. Nothing validates an input type when you save, so a misspelled one fails when the form renders, not on the call.
• A checkbox with validation: accepted is shown as a box the visitor must tick before the form sends. Use it for a privacy statement. A checkbox that signs a visitor up for a mailing list is a different field with a consent object, and the platform refuses to save it without a subscription type and an email or phone input on the form, so leave it out of a plain quote request.
• lead_stage files the sender in the customers App when the form carries an email or phone: a person not known yet is created as a contact at that stage, and anyone further along stays where they are. null files no contact. This is what the platform does on its own; set null if your CRM is the only system that should create the person.
• A form is capped at 60 named inputs by default (the tenant setting Maximum fields per form); a longer definition is a 422 naming both numbers.

The form is born a draft, and a draft renders nothing. Publish it by moving its status:

curl -s -X PUT "https://api.revenexx.com/v1/forms/<FORM_ID>" \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "live"}' | jq '{slug, status}'

{
  "slug": "quote-request",
  "status": "live"
}

Until then your Theme's GET /api/forms/quote-request answers 404, and a submission straight to the API is refused with 422 and reason: form_not_live. If the form 404s, check the status before the slug. Editors can build and publish the same form in Cockpit's Form Builder; the API is the same route.

2. Place the form on a page

How you place it depends on the layer your Theme extends.

A Theme on @revenexx/cover-theme has a form block. An editor drops it into a content section in Cockpit and picks the form from a list of the tenant's live forms, so nothing is typed and nothing is a deploy. See the block catalog and Forms.

export default defineAppConfig({
  formsService: "api",
});

Whatever you place, the words around the form come from your Theme's translation files: add forms.success (the thank-you when the form has no success_message) and forms.submit (the button label when it has no submit_label) for every language you serve. The rest of the forms.* keys already exist in the layer.

A Theme on @revenexx/cover only, such as the custom-theme package, has no blocks, but the layer ships two components, and custom-theme already sets formsService to api. RevenexxForm renders a form by slug. FormPage wraps it in a page with a title, an intro and a card, and the starting point already uses it for /contact:

<script setup lang="ts">
const { t } = useI18n();
</script>

<template>
  <FormPage
    slug="quote-request"
    :title="t('forms.quoteRequest.title')"
    :intro="t('forms.quoteRequest.intro')"
    :context="{ sku: $route.query.sku }"
  />
</template>

context pre-fills fields by name, which is how a "Request a quote" link on a product page can arrive with the article number already in the form: link to /quote-request?sku=<SKU>. Add the two forms.quoteRequest.* strings to your Theme's translation files.

custom-theme also ships a /price-request page for a form with the slug price-request, whose article field is filled from ?product= or ?sku= in the link. If your quote request is about one article, create your form under that slug and reuse the page instead of writing a new one: mark the article node with "rxKind": "product" so the layer pre-fills it. Put <RevenexxForm slug="quote-request" /> straight into any other page if you do not want the page shell.

3. Check the routes, and use mock mode on purpose

Two routes carry everything, both on your storefront's own origin:

A third, GET /api/forms, lists the live forms by slug and name, so a page can offer a "Request a quote" link only when the form exists. It answers an empty list rather than an error when the Forms App is unreachable.

Check the first one before you look at the page. It answers from the tenant, so with a running storefront:

curl -s http://localhost:3000/api/forms/quote-request | jq '{slug, settings, honeypot, fields: [.definition[].name]}'

Mock mode is a switch with a trap. The cover layer reads each domain from its own service setting, and formsService is mock in the layer's defaults. custom-theme sets it to api; cover-theme does not, and neither does a Theme of your own unless you do (step 2). In demo mode the routes serve four bundled demo forms (contact, price-request, callback and widerruf, written in German with an English overlay), record nothing, and answer 404 for any other slug, including yours. The symptom is a form that exists on the tenant and shows "This form is not published". The block picker's local-development list (contact, newsletter) is a separate sample list and does not match these four. In the demo shop a dev panel row, Authored Forms, flips between its mock entry (labelled "Mock (3 Demo-Formulare)") and Live (Public API) through the cover-dev-mode cookie. Mock mode is the right choice for working on the look of a page without credentials; it proves nothing about your form.

Everything that can go wrong in reading a form looks the same on the page: the component swallows the error and shows "This form is not published". Call the route above to see the real status.

4. Handle the submission

The form validates in the browser with FormKit, sends, and then shows one of three results. You do not write this logic, but you do decide what the visitor reads.

Four details decide how this behaves in practice:

• The success text and the button label belong to the form. Set success_message and submit_label in the form's settings, as in step 1, and do not hard-code them. They are only the form's own words in its default_locale; a visitor reading another language gets the Theme's translated strings instead, so write the Theme's forms.success and forms.submit keys for each language you serve.
• A multi-step form can end on a thank-you page. A $rxStep marker with "kind": "thankyou" marks a content-only last step, which the storefront shows above the success message after sending.
• The route checks less than the browser does. It drops any key the form does not declare, but it does not check that a required field is present, so required fields are not enforced on the platform: treat data as untrusted and check what you rely on in the workflow in step 5.
• Every failure after the browser's own check is the same sentence. The component shows one generic error for a 400, a 404, a 429 and a 500, so a key without the forms.* scopes looks like a server fault. To tell them apart, watch the network tab, or log the status in your Theme's server route. Do not log the submission body, it is personal data (Logs).

Spam protection is a honeypot, and it ships switched off. There is no captcha and no form-specific rate limit (as of 2026-11); the only limit is the gateway's per-tenant budget, which answers 429 (Rate limits). The honeypot is a decoy field the storefront renders hidden: a person never fills it, a bot fills everything. Turn it on in Cockpit under the Forms App's settings by naming a decoy field, Honeypot field name (for example contact_reference, a name that is not one of your form's fields). Your Theme then renders it for you.

The platform strips the decoy before it stores the answers, as the API reference for POST /v1/forms/submissions says, so it never reaches your CRM. What to do with a caught submission chooses between the two outcomes in the table: the default, flag, keeps the row with status spam so a false positive can be recovered from the inbox; reject refuses it and stores nothing. The settings are read per market (Settings).

Notifications are not sent by the Forms App. It only works out who should be told, once, when the row is written: the form's own notify_email, else the tenant's Fallback notification recipient. The address is stored on the submission as metadata.notify_email, with metadata.notify_source saying which of the two won. Delivering the mail is step 5.

5. Forward submissions to your CRM or ERP

Every stored submission is announced as an event with the topic revenexx.forms.form.submitted, with the submission row as its payload. A refused submission has no row and so no event. Do the forwarding in an Integration Studio workflow rather than from your Theme's submit route: no server of yours has to be up, a failure lands on a run you can read and replay, and a form stays a data-collection surface.

Read the topic and a real payload from your tenant's catalog first. The forms event declares no required fields in the event catalog, so the sample there is your reference, not a table on this page. The catalog has no documented scope yet (as of 2026-10), so use a development key with *:

curl -s https://api.revenexx.com/v1/events/catalog \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
  | jq '.emits[] | select(.app == "forms" and .name == "form.submitted") | {topic, sample}'

In Cockpit, open Integration Studio → Workflows → New and add an Event trigger with the subject revenexx.forms.form.submitted. The trigger drops a repeat delivery of the same event, so one submission starts one run (Event triggers). Then add these nodes:

1. If condition: continue only when the submission's status is not spam. Under the default policy a caught submission is stored as spam and still announced, so without this a bot reaches your CRM.
2. If condition on the fields you rely on, such as email being present. The route does not check required fields, as step 4 says.
3. HTTP Request to your CRM's lead or enquiry endpoint, mapped from the submission. Set the node to route a failure to an error branch instead of failing silently (Failure handling).
4. Send Email to the sales desk, using metadata.notify_email as the recipient, with an SMTP credential in Integration Studio → Credentials.

The event's own fields sit under data, and the submission row is that payload. The answers the visitor typed are the row's data object, so they sit one level deeper. Build the expressions with the picker against the sample from the catalog; the shape below is what the platform's contract describes and was not yet checked against a live run of this form (as of 2026-11):

Values keep the type of their input: a number field arrives as a number, a single checkbox as true or false, a multi-select as an array. Treat every value as end-user data: send it only to the systems that need it and keep it out of run logs.

A submission can also be read, triaged and exported through the API (GET /v1/forms/submissions, PUT /v1/forms/submissions/{id}) for work that is not event-driven; see Forms.

Troubleshooting

Where to go next

Start with Forms: the delivery route, the inbox, triage, retention and deleting a form, which you need once the form is live.

• Build a block: if the form needs a layout the standard component does not give you.
• Turn an accepted quote into an order: the other quote path, for a buyer who asks about a whole cart.
• Event triggers and the node catalog: the building blocks of the workflow in step 5.
• Hand an order to the ERP: the same loop for orders, including retries that do not double-book.