Offer fields

Where attributes describe the product itself (material, colour, size), offer fields describe your listing of that product: your price, your stock level, your lead time to ship, your barcode, handling charges, and so on. Two sellers offering the same product on the same marketplace share the product attributes but have different offer fields.

Each marketplace defines its own set of offer fields. The plugin downloads that list per connection, and on the Offer Field Mappings page you tell it, for each operator offer field, which Shopware data should be sent.

Where to find it

Open the Mirakl admin module and click the Offer Field Mappings tile in the Quick Start section.

The list shows your existing mappings with these columns:

• Offer Field — the operator’s offer field (the thing you map into).
• Field Type — the data type the operator expects (text, number, date, list, …).
• Required (Mirakl / Export) — two flags, separated by a slash. First: whether the marketplace requires this field. Second: whether the plugin treats it as mandatory at sync time (see Required vs optional below).
• Source Type — what kind of Shopware data you are reading from.
• Source Value — the specific field or value behind the source type.
• Default Value — fallback used when the product has no value (see below).
• Connections — the connections this mapping applies to.

You can filter by Connection, Source Type and Offer Field. The toolbar offers Refresh, Add Mapping, Export Mappings and Import Mappings.

Pull the operator’s offer field list

The list of available offer fields you can map comes from a refresh:

• The setup wizard refreshes them for you in step 6 (Offer Fields).
• On the Offer Fields page (Quick Start → Offer Fields) the Refresh Fields button pulls the operator’s current list any time. Run it whenever the operator announces a schema change.

Seed the defaults — the recommended starting point

There is no Auto-Map button for offer fields. The equivalent is the setup wizard’s step 7, where a button labelled Apply Defaults creates a set of sensible default mappings (price → price, stock → stock, EAN → ean, and so on). Defaults are added only where no mapping yet exists, so applying them twice does not create duplicates.

At the same wizard step you can also import a JSON file exported from another connection.

If you skipped that step or want to add more mappings later, use the Offer Field Mappings page directly.

Add or edit a mapping

Click Add Mapping in the toolbar (or open an existing row and choose Edit from the context menu). The dialog asks for:

• Offer Field — pick the operator field you want to map.
• Connections — which connection(s) the mapping applies to. One mapping can target several connections, but you cannot have two mappings for the same offer field on the same connection.
• Source Type — what kind of Shopware data you want to read from. The fields in the dialog change depending on your choice (see the table below).
• Source Value — depends on the source type: a product-field name, a custom-field key, a property-group reference, a static text, and so on.
• Default Value — a fallback used when the product has no value. The lock icon controls the behaviour: locked means no default — fall back to the standard logic; unlocked means send this exact value, even if blank.
• Required for export — a per-mapping safety check. When on, products with no value for this offer field are skipped during offer sync — they are simply excluded from the batch sent to the marketplace.

Source types

The list of available source types is closed — pick the one that best matches how you store the value in Shopware.

Source type	What it resolves to
Product Field	One of the native product fields: Name, Description, EAN, Product Number, Stock, Price, Weight, Width, Height, Length, Manufacturer Number, Unit (name), Purchase Unit, Reference Unit.
Custom Field	A Shopware custom field. The dialog lets you pick from a custom-field set or type the key by hand (with dot notation for nested values).
Property Group	The value of a product property group.
Product Category	A smart helper: use the Mirakl category if one is mapped, otherwise fall back to the Shopware category.
Mirakl Category	The mapped Mirakl category only (no fallback).
Shopware Category	The raw Shopware category, with no Mirakl mapping involved.
Product Image URL	URL of the product’s cover image.
Tax Rate	The product’s tax rate as a percentage.
EAN with SKU fallback	The product’s EAN if set, otherwise the product number (SKU).
Auto Product ID Type (EAN/SHOP_SKU)	The literal text EAN or SHOP_SKU, matching whichever value the previous helper returned.
Shop SKU (Product Number)	Always the product number.
Product ID Type: SHOP_SKU	Always the literal text SHOP_SKU.
EAN / GTIN	Always the EAN (empty if the product has none).
Product ID Type: EAN	Always the literal text EAN.
Effective Stock	Physical stock or available stock (minus reserved). Both return 0 when the product is inactive.
Delivery Time	The product’s delivery-time minimum or maximum in days.
Mirakl Offer State	The per-product offer-state override, or the connection’s default offer state.
Static Value	A fixed text sent as-is for every product.

The EAN/SKU helpers and the Product-ID-Type literals come in pairs because operators typically want both a product-id value and a matching product-id-type literal. Map them as two separate offer fields with matching source types so they stay consistent.

Required vs optional

The list shows two flags side by side under Required (Mirakl / Export):

• Required by Mirakl — comes from the operator’s field definition. If Mirakl marks a field as required, the operator rejects offers without it.
• Required for export — a per-mapping safety check on your side. When on, products with no value for this field are skipped during offer sync — they are simply not sent. Useful as a soft gate, e.g. skip products without an EAN rather than fail their offers.

Turning off Required for export on a field the marketplace itself requires triggers a warning in the dialog: doing so may cause sync errors or rejected offers downstream.

Value rules (transformations)

Each saved offer-field mapping can carry a chain of value rules (the editor is labelled Value transformations) that adjust the resolved value before it is sent.

Open the mapping in Edit and click Value transformations in the dialog footer (the button shows a count of existing rules). The available rule types are the same as for attributes: Replacement, Regular expression, Remove HTML, HTML → plain text, Lowercase, Uppercase, Capitalize first letter, Title Case, Max length. Rules run by Priority, lower numbers first.

Common uses for offer fields:

• Cap a stock level — a Max length or regex rule that limits the quantity at a known operator ceiling.
• Normalise currency — a Replacement rule turning € into EUR if you store the symbol.
• Strip HTML — on product-description if the operator wants plain text.

Value rules can only be added to a saved mapping. If the Value transformations button does nothing on a new mapping, you will see an info notice asking you to save first. Save the mapping with Save, re-open the row via context menu → Edit, then click the button again.

Import / Export

The Export Mappings and Import Mappings buttons move an entire offer-field configuration between connections or between shops:

• Export Mappings opens a dialog where you pick a Source connection. The downloaded JSON file contains every offer-field mapping linked to that connection.
• Import Mappings opens a dialog where you pick a Target connection, an Import mode (Merge — keep existing mappings, only add new ones, or Replace — remove existing mappings of the target connection first) and the JSON file. The summary at the end reports how many mappings were Imported, Replaced, Skipped, and how many Missing fields (referenced in the JSON but absent from the target connection’s offer-field list).

The setup wizard’s Offer Field Mappings step accepts the same JSON format, so an exported file can be applied during first-time setup as well.

Tips & gotchas

Tip

Start with the operator’s required fields. Optional fields (handling charges, gift-wrap availability and so on) can be added later without breaking your existing offers. The setup wizard’s Apply Defaults covers most of the common ones.

Caution

Avoid mapping the price to a custom field. Shopware already handles prices natively, with tax, currency, list price and special price. Bypassing that with a custom field will desynchronise your shop and marketplace prices. Use Product Field → Price instead — it goes through Shopware’s native price resolver and respects the connection’s sales channel context.

Note

A change to a Shopware field used by an offer-field mapping automatically triggers an offer sync for the affected products. A change to the mapping itself does not re-sync existing offers — they will be re-synchronised the next time their source field changes, or you can trigger a manual sync per connection.

Caution

You cannot have two mappings for the same offer field on the same connection. If you need different rules per product, model the differences with Static Value plus Required for export rather than duplicating the mapping.

Related

• Offer sync — uses the offer-field mappings at sync time
• Attributes — describes the product itself (rather than your offer of it)
• Offer states — separate from the Mirakl Offer State source type