Shopify custom field planning for upload jobs starts with one fact: a metafield definition must exist in your store before an upload team can enter any data into it. Custom fields, called metafields in Shopify, let you store structured product data beyond the standard title, description, price, and SKU fields.

Planning which fields you need and setting up their definitions before work starts is the step that decides whether your team can enter data straight away or has to stop and wait. The planning work, deciding on namespaces, keys, and content types, is yours to do first.

Key takeaways

  • A metafield definition (namespace, key, and content type) must exist in your store before an upload team can enter any value into it.
  • The namespace and key of a definition cannot be changed after it's saved, so a naming mistake means deleting the definition and losing any existing values.
  • Shopify offers standard definitions for common fields like materials, care instructions, and ISBN, and those are worth checking before creating custom ones.
  • Your upload team needs a written brief listing each custom field, what goes in it, and what to enter when a value is unknown.
  • Shopify custom field planning for upload jobs typically takes one to two hours for a standard product range and prevents far more rework than that.

Shopify custom field planning for upload: how definitions work

Close-up of a product spec sheet beside a keyboard showing metafield namespace and key entries

A metafield definition in Shopify has three required parts:

PartWhat it isExample
NamespaceA prefix that groups related fields and identifies who owns themcustom, product_info
KeyThe field name within the namespacematerial, country_of_origin
Content typeThe format of the value: text, number, date, true/false, and othersSingle-line text, Number (integer), Date

Together, the namespace and key form the full field identifier, written as custom.material or product_info.country_of_origin (as of November 2026, per Shopify's metafield documentation).

Once you save a definition, you cannot change the namespace, key, or content type. If you get any of these wrong, you have to delete the definition and re-create it. Any values already entered are lost. That is the main reason to plan carefully before an upload starts, rather than creating fields on the fly.

Check Shopify's standard definitions first

Before creating any custom definitions, check whether Shopify already has a standard definition that covers your field. Standard definitions are pre-built for common product data: materials, care instructions, ISBN, country of origin, and others (as of November 2026, Shopify Help Center).

Standard definitions use a fixed namespace (usually descriptors or similar) and work across Shopify themes and third-party apps automatically. If your store uses a theme that supports metafields natively, a standard definition displays without any extra theme code. A custom definition in a non-standard namespace may need template adjustments.

To check: in your Shopify admin, go to Settings > Custom data > Products (as of November 2026), then click Add definition. The dialog shows suggested standard definitions at the top. If one matches your field, use it.

Decide which products need custom fields, and what data they carry

Not every product in a catalog needs the same custom fields. Before creating any definitions, map out which product categories require structured extra data.

For example:

  • A range of kitchen appliances might need Wattage (number) and Certifications (text) fields that clothing products don't use.
  • A skincare range might need Ingredients (multi-line text) and Shelf life after opening (number) that furniture products don't use.
  • A book catalog needs ISBN (already a standard definition in Shopify) and Publisher (single-line text).

Write a table that lists each product category and the custom fields it needs. This becomes the brief for creating definitions and for briefing your upload team on what to enter.

A product can have up to 250 metafield definitions (as of November 2026, per Shopify's documentation). Most catalogs use far fewer than that, but if your range is complex, a naming scheme that groups fields by product type helps.

Name your namespaces and keys before you create anything

Namespace and key names are permanent. Spend ten minutes settling on a convention before you log in.

A few practical rules:

  • Use custom for merchant-owned fields unless you have a reason to group them differently. The custom namespace is Shopify's intended home for merchant-defined data, and it's immediately recognizable.
  • Keys should be lowercase with underscores: country_of_origin, not Country of Origin or countryOfOrigin. Shopify enforces alphanumeric, hyphen, and underscore characters; keys must be three to 64 characters long.
  • Be specific over clever: material_primary is clearer than mat1. Your upload team, your theme developer, and anyone who works on the store later will all thank you.
  • Don't abbreviate unless the full word exceeds 64 characters. weight_grams is fine; wt_g is not.

Write these down before creating any definitions. They are inputs to the team brief in the next step.

Create the definitions in Shopify admin before briefing the team

Shopify admin custom data settings page on a monitor in a home office setting

Once you have your field list and naming scheme, create the definitions in Shopify admin. For each field:

  1. Go to Settings > Custom data > Products, then Add definition.
  2. Enter the name (this is the display label; it doesn't have to match the key exactly).
  3. Edit the namespace and key to match your planned convention.
  4. Choose the content type. Pick the most specific type that fits: a whole number is Number (integer), a decimal weight is Number (decimal), a yes/no value is True or false. Avoid using single-line text as a catch-all when a more structured type fits.
  5. Set any validation rules that apply (minimum and maximum values for numbers, character limits for text).
  6. Save.

Do this for all definitions before handing the brief to your upload team. A team doing Shopify product data entry cannot enter a value for a field that doesn't exist yet.

Write a custom fields brief for your upload team

An upload team can only enter what you've told them to enter. The brief for custom fields needs to cover:

  • The display name of each field, as it appears in the Shopify product admin
  • What data to enter (and in what format, for text fields)
  • Sample values for at least two or three products
  • What to enter when a value is genuinely unknown (leave blank, enter "Unknown," or flag for review)
  • Which product types the field applies to

For example:

Field nameWhat to enterSample valueIf unknown
Primary materialMain material only, sentence caseStainless steelLeave blank
Country of originCountry name, Title CaseGermanyLeave blank
WattageNumber only, no unit1200Leave blank

This brief sits alongside your general upload brief, which covers product titles, descriptions, images, and standard fields. The article on what to send your upload team covers the full handover document if you need to build one from scratch.

What upload teams cannot do with custom fields

It's worth being clear about what a done-for-you upload team handles and what it doesn't.

A team entering product data can:

  • Enter values into existing metafield definitions
  • Follow your brief for format and content rules
  • Flag products where a required custom field value is missing from your source data

A team cannot:

  • Create new metafield definitions (that's a store-owner action in Shopify admin settings)
  • Change the content type of an existing definition
  • Delete or rename a definition
  • Decide independently what a field should be named or how it should be structured

The planning and setup is always the merchant's step. The Shopify product data entry checklist includes a section on confirming your custom fields are ready before a job starts, which is a useful reference.

For related decisions about how products are structured before an upload, the article on Shopify product types for upload jobs covers the product type field and when it matters.

Frequently asked questions

Can my upload team create metafield definitions for me?

No. Metafield definitions are created and managed in Shopify admin under Settings > Custom data, and that's a store-owner action. An upload team entering product data can fill in values for definitions that already exist, but creating, changing, or deleting the definitions themselves is outside the scope of product data entry work.

What content types does Shopify support for product metafields?

As of November 2026, Shopify supports single-line text, multi-line text, integer numbers, decimal numbers, dates, date and time, true/false, file references, product references, variant references, collection references, page references, URL, color, and weight values, among others. The full list is on the Shopify metafield types reference page. Choose the most specific type that fits your data, since it affects how the field is validated and displayed in your theme.

What happens if I create a metafield definition with the wrong key name?

You'll need to delete the definition and create a new one with the correct key. The namespace and key cannot be edited after a definition is saved. Any values already entered against the old definition are deleted when the definition is deleted. This is why planning the namespace and key before you start entering data matters, especially at scale.

Do I need custom fields, or will Shopify's standard fields cover my products?

Shopify's standard product fields (title, description, price, SKU, weight, barcode, vendor, and product type) cover most catalog needs. Custom fields are worth adding when you need structured data that doesn't fit those fields: technical specifications, regulatory information, compatibility details, or brand-specific attributes. If you're adding a short note to a few products, the description field or product tags may be enough. For anything a buyer or search engine might filter or surface by, a metafield with a defined type is cleaner.