# Set up Inkwell's metafields and licenses

Chapter 7 of the Inkwell user guide.

Inkwell's preview pages, checklists, the details, page counts, Works with chips and before and after images read **product metafields** in the `custom` namespace, the one Shopify admin uses when you create a definition. License cards read a **metaobject** called `license`. Two **product tags** add badges. You don't need an app, and you only need the data for the features you use: every feature hides when its data is empty, or falls back to its section or block settings, so nothing breaks while you fill them in.

In Shopify admin these live under **Settings › Custom data** (called **Metafields and metaobjects** in newer versions of the admin).

## What Inkwell reads

| Name (yours to choose) | Namespace and key | Owner | Type | Example | What it does |
| --- | --- | --- | --- | --- | --- |
| Preview pages | `custom.preview_pages` | Product | **File**, **List of files** (images) | 12 page images | The **What's inside** strip, the flip-through and the open spread (chapter 9). Each file's alt text is its label. |
| What's included | `custom.included` | Product | **Single line text**, **List of values** | 120 undated pages · PDF + note-app file · A4 and US Letter | The ticked **What's included** checklist (chapter 9) |
| File format | `custom.file_format` | Product | **Single line text**, one value (a list of values also works: entries are joined with commas) | PDF + hyperlinked PDF | **Format** in The details, and on the compare page |
| Page count | `custom.page_count` | Product | **Integer** | 120 | **Pages** in The details, the "120 pages" chip on product cards, and the compare page |
| File size | `custom.file_size` | Product | **Single line text**, one value | 24 MB | **File size** in The details, and on the compare page |
| Works with | `custom.works_with` | Product | **Single line text**, **List of values** (one value with commas also works) | GoodNotes · Notability · Print at home | The **Works with** chips (chapter 8), the hero's Works with row when you pick the product there, and the compare page |
| Before image | `custom.before_image` | Product | **File**, one value (images) | `moody-before.jpg` | The **Before and after** slider under the product's gallery (chapter 11) |
| After image | `custom.after_image` | Product | **File**, one value (images) | `moody-after.jpg` | The same slider; both images are needed |

**The `license` metaobject** (one entry per license you sell, chapter 10):

| Field name (yours to choose) | Key | Type | Example | What it does |
| --- | --- | --- | --- | --- |
| Name | `name` | **Single line text**, one value | Commercial | Matched to the value of your License option, ignoring capitals and spaces at the ends |
| Summary | `summary` | **Single line text**, one value | For one small business | The line under the license's name on its card |
| Allowed | `allowed` | **Single line text**, **List of values** | Everything in Personal · Use in client work and products you sell · Up to 500 printed copies | Ticked lines on the card and rows in the compare table |
| Not allowed | `not_allowed` | **Single line text**, **List of values** | Reselling the files | Crossed lines on the card and the "Not allowed" row in the compare table |

And these product tags (capitals don't matter):

| Tag | What it does |
| --- | --- |
| `bestseller` | A **Bestseller** badge on the product's card |
| `new` | A **New** badge, whatever the product's publish date. Without the tag, products get the badge for **Theme settings › Product cards › New badge for new products** days (21) after they're published. |

The **Free** badge needs no tag: it shows on any product whose price is 0. Two more metafields are filled in by review apps, not by you: `reviews.rating` and `reviews.rating_count` give the stars on cards and "4.9 · 312 reviews" in the **Product metadata** block. And a **Spec row** (chapter 6) can show any metafield you create.

## Step 1: create the product metafield definitions

In admin, go to **Settings › Custom data › Products** and click **Add definition** for each metafield you need:

1. Type the **Name** (yours to choose; it's what you see when you edit a product).
2. Check the **Namespace and key** under it and change it to exactly the key in the table above. Shopify suggests `custom.` plus the name, so "Page count" gives `custom.page_count`, but "Number of pages" would give `custom.number_of_pages`, which the theme won't find. Keys are case-sensitive.
3. Click **Select type** and choose the type in the table:
   * **Preview pages**: **File**, then **List of files**. Limit it to images if you like. A file with **One value** isn't read as a list, so the strip stays empty.
   * **What's included** and **Works with**: **Single line text**, then **List of values**.
   * **File format** and **File size**: **Single line text**, **One value**.
   * **Page count**: **Integer**, **One value**.
   * **Before image** and **After image**: **File**, **One value**. Limit them to images if you like.
4. **Save**.

## Step 2: create the license metaobject definition

Only if you sell licenses. Go to **Settings › Custom data**, open **Metaobjects** and click **Add definition**:

1. **Name**: "License". Check that its **Type** (the handle shown under the name) is exactly `license`. The theme reads `metaobjects.license`, so a definition whose type is `licence` or `license_tier` won't be found.
2. Add four fields with **Add field**, checking each field's **Key**:
   * **Name**, key `name`: **Single line text**, **One value**. Mark it required if you like.
   * **Summary**, key `summary`: **Single line text**, **One value**.
   * **Allowed**, key `allowed`: **Single line text**, **List of values**.
   * **Not allowed**, key `not_allowed`: **Single line text**, **List of values**.
3. Under **Access** (or **Options**), turn **Storefronts** access **on**. This is the step people miss: without Storefronts access the theme can't read your entries, and every license card falls back to the Variant picker block's text.
4. **Save**.

## Step 3: add your licenses

Go to **Content › Metaobjects › License** and click **Add entry** for each license: Personal, Commercial, Extended or whatever you call yours. Type its **Name** exactly as the value appears in your products' License option ("Commercial" matches "commercial" and " Commercial ", but not "Commercial license"). Add each allowed and not-allowed line as its own list entry. Write cumulative licenses the way the presets do: start a higher license with "Everything in Personal", and the compare table ticks everything the lower license allows for it too (chapter 10). The theme reads up to 50 entries.

## Step 4: fill in your products

Open a product in admin and scroll to **Metafields**: every product definition you created is listed there.

* **Preview pages**: upload or choose the page images. Give each file alt text that names the page, such as `Page 18 of 120 · Weekly spread`: the alt text is the label under the page and the name screen readers hear. Edit a file's alt text in **Content › Files** (click the file).
* **What's included** and **Works with**: add each line as its own entry.
* **File format**, **Page count** and **File size**: type the value.
* **Before image** and **After image**: choose both.

There's a second way to add preview pages, without the metafield: add the page images to the product's **media** and start each one's alt text with `#inside`, such as `#inside Page 18 of 120 · Weekly spread` (chapter 9). To fill many products at once, use **Bulk edit** from the products list and add the metafield columns. Add the `bestseller` and `new` tags in the product's **Tags** field.

## How the theme reads what you type

* **Preview pages** show in list order. A file with no preview image (a ZIP, say) is skipped. The `#inside` tag and the space after it are taken off the label wherever it would show; a page with no alt text is labelled by its position ("Sample page 4"), never by an invented page number.
* **What's included** shows each entry as a ticked line, in your order, in two columns.
* **File format** shows as you typed it ("PDF + hyperlinked PDF"); a list shows as "PDF, PNG".
* **Page count** shows as the number in The details (Pages: 120) and as "120 pages" (or "1 page") on cards.
* **File size** shows as you typed it: write the unit with a space, "24 MB".
* **Works with** shows one chip per entry, each with a generic icon picked from its words (chapter 8), up to the block's **Chips to show** (6).
* **Before image** and **After image** need to show the same scene at the same size and shape: the slider lays one over the other.

## What shows without the data

| Missing | What happens |
| --- | --- |
| Preview pages (metafield and `#inside` media) | No strip and no flip-through; with a What's included list, the checklist shows alone. In Featured product's **Open spread**, the product's gallery shows instead. |
| What's included | No checklist; the strip shows alone |
| File format, Page count, File size | That row of The details is hidden; with Page count empty, cards show no page chip |
| Works with | The Works with block's **Fallback list**, if you typed one; otherwise no chips and no gap |
| Before image or After image | The Before and after block's own **Before image** and **After image**; with neither pair, nothing |
| License entries (or Storefronts access off) | The Variant picker block's license text, matched by name, then by position (chapter 10) |

In the theme editor, features with no data show a sample tagged **Sample** so you can see the design: six drawn planner pages and three checklist lines in What's inside, three sample Works with chips, a drawn before and after scene, the Instant download badge, and the three default licenses in the License guide section. Shoppers never see them.

> **Note:** Settings you type into a block on the product template (the Works with block's **Fallback list**, the Before and after block's images, the Variant picker block's license text) show on **every product that uses this template**. Use them for a catalog where most products are alike, or on a template you make for those products (in the theme editor, **Create template** from the product template and assign it to those products in admin). For a mixed catalog, use the metafields.