Custom Tables Overview

Custom Tables let a merchant define their own tables and records for structured data the platform
has no built-in model for: store locators, FAQ entries, size charts, product care guides, warranty
registrations, delivery zones. A table can stay private to the back office, or be published so the
storefront can show it.

Requirements

The Advanced customization module on the company's subscription.

A Shopranos admin user with the Customization permission.

Tables are managed in the Shopranos admin at https://shopadmin.shopranos.eu, under
Settings → Developer Tools → Custom Tables.

To show a table on the storefront: the Noir theme's Custom Table component, or theme
JavaScript calling the read-only storefront API. Kitchenware has no Custom Table component.

How it fits together

Define a table: an identifier, a name and up to 50 typed fields.

Add records: one at a time in the record editor, or in bulk from a CSV file.

Link records to products, brands, categories or collections when they describe one of them.

Publish the table to the storefront, if shoppers should see it.

Show it with the Noir Custom Table component, or read it from theme JavaScript.

The model

Object	What it holds
Table	Its Identifier (permanent key), Name (display label), storefront visibility, Fields and a schema version.
Field	A Field name, a Type, and two flags: Required and Queryable.
Record	One row: a value for each field it uses, plus optional entity links.
Entity link	A `type` / `id` pair pointing at a platform entity, for example `product` plus the product's id.

A record belongs to exactly one table, and every table belongs to one company. Nothing is shared
between merchants.

Naming rules

Table identifiers and field names follow the same rule: a lowercase letter first, then lowercase
letters, digits or underscores, up to 50 characters (^[a-z][a-z0-9_]{0,49}$).

Example	Valid
`store_locations`	✅
`StoreLocations`	❌ uppercase
`store-locations`	❌ hyphen
`2nd_table`	❌ starts with a digit

Field names must be unique within a table, and id is reserved.

The identifier cannot be changed after creation, and renaming a field is a data migration (see
Schema changes and versioning below). Name them after the concept, not the current wording. The
table Name is free text and can change at any time.

Field types

Type (admin label)	Holds
Text	Any text. Leading zeros are kept, so codes such as `00042` stay intact.
Number	Whole or decimal numbers.
Yes / No	`true` or `false`.
Date & time	A date and time. See the warning below.

There are no list, object or nested field types. If a record needs a list whose items must be
validated or filtered individually, give the items their own table and link both to the same entity.

⚠️ Dates are compared as text. The record editor and the CSV importer store every date in
ISO-8601 UTC, for example 2026-01-22T09:30:00.000Z, so filtering and sorting work. Anything else
that writes records must use exactly the same format; a mix of formats silently returns the wrong
records.

Required fields

Required is checked whenever a record is saved, not retroactively. Adding a required field to a
table that already holds records does not break them; they stay readable. But each one fails to save
until the new field is filled in. An empty (null) value counts as missing.

Queryable fields

Only queryable fields can be used in filters, and a table has a budget of 10 of them. A field
must be both queryable and required to be used for sorting. Choose them deliberately; see
Designing Fields, Queries and Links in this section.

Schema changes and versioning

A new table starts at schema version 1, and every save of its configuration increases it. Existing
records are not migrated or rewritten, so a table can hold records written under several
versions. Validation always runs against the current fields:

You change	Existing records
Add an optional field	Fine. Older records simply have no value for it.
Add a required field	Still readable; each fails to save until the field is filled in.
Remove a field	Its values stay on each record, and are still returned by the storefront API and shown by a Custom Table component that lists every field, until the record is saved again without them.
Change a field's type	Old values no longer match; saving the record forces a correction.
Rename a field	Treated as remove plus add, so the old values stay on each record under the old name.

Prefer adding a new optional field over reshaping an existing one. Removing a field from a published
table does not withdraw its values: rewrite or delete the affected records, or unpublish the table.

Limits

Limit	Default
Tables per company	50
Fields per table	1–50
Queryable fields per table	10
Data per record	64 KB
Entity links per record	50
Records per table	No limit
Storefront page size	25 by default, 100 at most
Storefront cache	5 minutes
CSV import file	10 MiB, 10,000 data rows, 256 columns

In this section

Managing Custom Tables in the Shopranos Admin: creating tables, publishing, editing records,
links and filters.

Importing Records from CSV: bulk-loading records, mapping columns and retrying failed rows.

Designing Fields, Queries and Links: how to structure a table so it can be filtered, sorted and
shown on the right pages.

Using Custom Tables on Your Storefront: the Noir component and the storefront API.

Not available yet

Bulk update, record export, full-text search, aggregation, uniqueness constraints, translated field
values, nested fields, writing records from the storefront, scheduled imports, and webhooks or ERP
sync for custom tables.

Custom Tables Overview

Requirements#

How it fits together#

The model#

Naming rules#

Field types#

Required fields#

Queryable fields#

Schema changes and versioning#

Limits#

In this section#

Not available yet#