Pre-filled Configuration Links

A pre-filled configuration link opens the configurator for a customer with selections, quantities, and contact details already set. You construct the link by encoding a JSON instruction object and appending it to the configurator URL as a query parameter.

https://your-configurator-url/?preconfig=ENCODED_JSON

This is useful for CRM integrations, CPQ workflows, marketing campaigns, distributor portals, and any situation where you want to send a customer straight to a ready-made configuration rather than an empty form.

---

Step 1 — Write the JSON

The instruction object is a single JSON value (the SDK type is TPreConfig). It describes what to load when the customer opens the link.

Top-level keys

Key	Required	Purpose
configs	Yes	One or more product configurations to pre-load (forms, names, quantities, element prefills).
requestFields	No	Customer and order metadata shown at checkout (name, email, and dynamic request fields).
projectName	No	Name of the overall configuration / project in the UI — the same label the customer sees as the draft or configuration title.
reset	No	When true, clears the current browser session before applying the rest of the payload (see Starting from a clean session).

Full example

{
  "projectName": "Quote QT-2024-001 — Acme Corp",
  "reset": true,
  "configs": [
    {
      "configName": "My Configuration",
      "configQuantity": 1,
      "formId": "product-form-name",
      "prefills": [
        {
          "elementId": "color-selection",
          "value": "red"
        },
        {
          "elementId": 42,
          "value": "SKU-1234"
        }
      ]
    }
  ],
  "requestFields": [
    {
      "requestFieldId": "email",
      "value": "customer@example.com"
    },
    {
      "requestFieldId": "quote-number",
      "value": "QT-2024-001"
    }
  ]
}

projectName — configuration / project title

projectName sets the configuration name for the session: the title shown in the configurator header, checkout summary, and saved drafts. In the SDK this is stored as submitSubstore.draftName.

Use it when the link should open with a meaningful label already filled in — for example a CRM quote number, campaign name, or customer project title — so the customer does not have to type it.

• If you omit projectName, the configurator keeps whatever name the session already had, or falls back to your default when creating configs from scratch.
• If you include projectName, that string is applied when the link is processed, after any optional reset cleanup (see below).
• When you export a session with the SDK (exportToPreConfig), the current draft name is written back into projectName, so you can round-trip links and saved payloads.

This is separate from configName inside each configs[] entry: projectName names the whole request / project, while configName names one line item (one configured product) in a multi-config cart.

Starting from a clean session (reset)

By default, opening a pre-filled link replaces the list of product configurations with those in configs, but it does not fully wipe checkout contact data or draft state that was already in the tab. That is usually what you want when adding or switching products while the customer keeps typing their email.

Set "reset": true when the link must behave like a fresh visit before your prefills run. The SDK then, in order:

1. Clears draft binding (draftId and related draft-only state), so the session is no longer tied to a previously loaded draft.
2. Removes all configurations, form state, BOM state, and realtime lookup state.
3. Resets contact details: name and email go back to empty with validation errors for required fields; dynamic request fields go back to defaults (empty strings, "false" for checkboxes, and required-field errors where applicable).
4. Applies projectName, requestFields, and configs from the link as usual.

Typical uses:

Scenario	Recommendation
Marketing link where the customer must not inherit an old half-finished cart	"reset": true
CRM link that should replace an open configurator tab entirely	"reset": true
Add a second product to an in-progress session	Omit reset (or false)
Same customer revises only product options but keeps contact details they already entered	Omit reset; only change configs / prefills

You can combine reset: true with an empty configs array to only clear the session (for example a “start over” URL with no products yet).

Note

reset is processed by the configurator when it reads the preconfig query parameter (via setupFromPreConfig). It is not a separate URL flag.

---

configs fields

Each entry in configs represents one product configuration.

Field	Type	Description
configName	string	Display name shown for this configuration
configQuantity	number	How many units of this product to configure
formId	string	The name or identifier of the configurator form to load
prefills	array	List of elements to pre-select — see below

prefills fields

Each entry in prefills targets a single form element (optionally inside a repeatable group).

Field	Type	Description
elementId	string or number	The slug or numeric ID of the form element. Use a number (no quotes) when referencing by ID
groupId	string or number (optional)	Slug or ID of the group when the element lives inside a repeatable or nested group. Omit for top-level elements.
value	string, number, boolean, or array	The value to set. For multi-select elements you can pass an array of slugs or SKUs. See accepted value types below.
quantity	number (optional)	Quantity for a quantifiable product option when the element supports quantities.

Accepted value types:

Element type	What to put in value
Select / radio / checkbox	Option slug or product SKU
Text	Any string
Number / range	A number
Toggle / boolean	true or false

Tip

Find slugs and IDs in the Mercura back-office under Form Builder → [your form] → [element]. For request fields, use the sub-field slug (preferred) or label text as requestFieldId. When using a numeric ID, write it as a number without quotes: "elementId": 42.

---

requestFields fields

Request fields capture contact or order details shown at checkout.

Field	Type	Description
requestFieldId	string	The slug or label text of the request sub-field (matched case-insensitively)
value	string	The value to insert

---

Step 2 — URL-encode the JSON

Browsers cannot read raw JSON in a URL — characters like {, ", and spaces must be converted to their percent-encoded equivalents first.

Quickest way:

1. Copy your JSON
2. Go to https://urlencoder.org
3. Paste the JSON and click Encode
4. Copy the result

Common conversions for reference:

Character	Encoded
{	%7B
}	%7D
"	%22
:	%3A
,	%2C
[	%5B
]	%5D
space	%20

---

Step 3 — Build the link

Append the encoded JSON to your configurator URL using the preconfig query parameter.

https://your-configurator-url/?preconfig=ENCODED_JSON

Example (before encoding):

https://onboarding.staging.config.mercura.dk/?preconfig={"configs":[...]}

Example (after encoding):

https://onboarding.staging.config.mercura.dk/?preconfig=%7B%22configs%22%3A%5B...%5D%7D

When a customer opens the link, the configurator automatically loads the specified form and applies all pre-selections.

---

Multiple configurations

You can pre-load more than one configuration in a single link by adding additional entries to the configs array.

{
  "configs": [
    {
      "configName": "Main Unit",
      "configQuantity": 1,
      "formId": "main-unit-form",
      "prefills": [
        { "elementId": "size", "value": "large" }
      ]
    },
    {
      "configName": "Accessory Pack",
      "configQuantity": 2,
      "formId": "accessory-form",
      "prefills": [
        { "elementId": "color", "value": "black" }
      ]
    }
  ],
  "requestFields": [
    { "requestFieldId": "email", "value": "customer@example.com" }
  ]
}

---

Common use cases

Use case	What to pre-fill
CRM integration	projectName (quote ID), customer email, product based on opportunity; use reset: true when the link must replace an open session
CPQ integration	Form, options, quantities, and projectName from the quote header
Marketing campaign	A specific product model with campaign-relevant defaults; reset: true so visitors do not keep an old cart
Distributor portal	Distributor-specific options, contact details, and branded projectName
Quoting workflow	Full configuration from a previous quote for revision
Start over link	{ "reset": true, "configs": [] } to clear the session without loading a product yet