Migration to 1.0
Custom fields are gone, product parameters replace them
Migration to 1.0
@behio/storefront-sdk 1.0.0 replaces the custom-field surface inherited from
warehouse data groups with product parameters: a curated layer the merchant
builds in the Behio admin. This is the only breaking change in the release.
Before and after
| 0.42.0 | 1.0.0 |
|---|---|
ProductDetail.customFields: ProductCustomFieldGroup[] | ProductDetail.parameterGroups: ProductParameterGroup[] |
| nothing on the variant | ProductVariant.parameterGroups: ProductParameterGroup[] |
types ProductCustomField, ProductCustomFieldGroup | types ProductParameter, ProductParameterGroup |
customFields query param on /catalog/products, /catalog/categories/{slug}/products, /catalog/facets | parameters, same shapes, keyed by parameter slug |
FilterField.groupKey, type = warehouse field type | FilterField.groupSlug, type = "enum" | "range" | "boolean", new unit |
Facet.groupKey, Facet.fieldType, key = field key | Facet.groupSlug, no fieldType, key = parameter slug |
DataGroupFieldType exported | removed from the public types |
getFilters() | getFilters({locale}), returns parameter-based filters |
| nothing | client.catalog.getProductParameters(slug, {locale}) |
| nothing | client.catalog.getProductParameterGroup(slug, groupSlug, {locale}) |
| nothing | useProductParameters(slug, {locale, groupSlug}) |
The full contract is in Products & Search and TypeScript Types.
What to change in a template
- Swap the spec table source:
product.customFieldsbecomesproduct.parameterGroups. Each group is{slug, name, parameters}, each row is{label, value, booleanValue, unit}. Array order is the display order. - Drop any code that filtered out empty rows. The server omits parameters without a value.
- Booleans are explicit now:
booleanValueis non-null only for boolean parameters, and thenvalueisnull. Render "Ano" / "Ne", not"true". - Rename the query param:
customFieldsbecomesparameters. The value shapes are identical ("bavlna",["cerna", "bila"],hmotnost_min: 100), only the keys change from data-group field keys to parameter slugs, which is exactly whatgetFiltersandgetFacetsnow hand you. - In the filter sidebar, read
groupSluginstead ofgroupKey, build the control fromtype(enum/range/boolean) and stop readingFacet.fieldType, which no longer exists. - Pass
localetogetFiltersso labels and enum values arrive in the shopper's language.
Why it was removed instead of deprecated
The old surface was a leak, not a feature. A warehouse data group is internal bookkeeping: supplier names, their product ids, original import descriptions. It used to be dumped into the storefront spec table and into filters and facets, which means a shop could publish its supplier archive on its own product pages without ever choosing to, and a visitor could filter by a field the page did not even show. That happened for real on 2026-07-31 with an import archive from a dropshipping supplier, so exactly the data a dropshipper hides from customers.
A deprecation period keeps the leak open for as long as it lasts, and the field was already returning data nobody had approved for publication. Keeping both paths would also have meant keeping warehouse types in the public payload, which is the thing that made the leak possible. So the surface is gone: the API can only return parameter groups the merchant curated, and filtering only works on parameters they marked filterable. What used to be a policy is now a property of the schema.
Nothing is lost on the merchant side
Shops that relied on the old table can generate a parameter group from what their products display today, in the Behio admin. The rows keep their labels and their order, they simply become an explicit, published-on-purpose set.