Public metafields

Color Swatches stores swatch data in Shopify metafields so you can render groups and variant colors yourself: in your theme, another app, or a headless storefront. The built-in widgets use the same data. No Color Swatches API token is required.

Product groups live on each product. Variant swatch colors live on the shop.

To render that data in a theme, see Reading swatch data in Liquid.

Where the data lives

Color Swatches writes its data to its own namespace, app--4638357--pl_swatches, in every store. Only Color Swatches can write there, and any theme Liquid can read it without changing a setting:

Data	Liquid
Product groups	product.metafields['app--4638357--pl_swatches'].groups
Variant swatches	shop.metafields['app--4638357--pl_swatches'].options

Use these in custom theme code.

Other apps can’t read the app’s namespace through the Admin API. To read the data from a headless storefront or another app, such as a search, filter, or SEO app, turn on Enable public metafields. Color Swatches then also writes public copies under the pl_swatches namespace:

Data	Public copy	Read it from
Product groups	pl_swatches.groups	Liquid, the Storefront API, the Admin API
Variant swatches	pl_swatches.options	Liquid, the Admin API

The pl_swatches namespace belongs to your store, so any app with metafield access, and any translation, can change these copies. Color Swatches’ own widgets never read them.

Enabling public metafields

1. In the Color Swatches admin, go to Settings > Product groups, and find the General section.
2. Check Enable public metafields and save.

Saving triggers a full resync that writes every group and the shop’s variant swatch data to the public namespace. Small catalogs finish in under a minute; very large ones take longer.

You can turn the setting off at any time. Color Swatches deletes both public copies, pl_swatches.groups on products and pl_swatches.options on the shop. Its own app--4638357--pl_swatches metafields stay in place, and the app keeps working without further changes. If your theme code reads pl_swatches, switch it to the app--4638357--pl_swatches namespace first.

Note that uninstalling the app does not remove the metafields - Shopify revokes the app’s access before it can clean up. See removing leftover metafields.

What gets written

The toggle controls two metafields:

	Product groups	Variant swatches
Namespace	pl_swatches	pl_swatches
Key	groups	options
Type	JSON	JSON
Owner	Product	Shop

Only products that belong to at least one group get groups.

In the Shopify admin you’ll find the groups definition under Settings > Custom data > Products, listed as “Platmart Swatches: Groups (public)”.

There is no definition for options under Settings > Custom data. Query it by namespace and key.

Product groups

Group data lives on each product that belongs to at least one group. In theme Liquid, read product.metafields['app--4638357--pl_swatches'].groups. The public copy, pl_swatches.groups, has the same payload.

Payload structure

The metafield value is always a JSON array, with one element per group the product belongs to. A product in a single-option group looks like this:

[
  {
    "group_id": 12345,
    "option_name": "Color",
    "type": "colors",
    "display_for": "products_and_collections",
    "linked": false,
    "swatches": [
      {
        "handle": "backpack-black",
        "name": "Black",
        "type": "one_color",
        "color_one": "#000000",
        "color_two": null,
        "image": null,
        "out_of_stock": false
      }
    ]
  }
]

If the product belongs to several groups, the array has multiple elements. Multi-option groups expand to one element per option slot, each with the same swatches shape.

Reading from the Shopify Storefront API

With public metafields on, headless storefronts can query the metafield field on a product through the GraphQL Storefront API:

query ProductSwatches($handle: String!) {
  product(handle: $handle) {
    id
    title
    swatchGroups: metafield(namespace: "pl_swatches", key: "groups") {
      value
    }
  }
}

The value is a JSON string. Parse it client-side to get the same payload you’d see in Liquid.

Reading from another app

With public metafields on, any Shopify app with the read_products access scope can read pl_swatches.groups like any other custom metafield. No special integration is needed.

Variant swatches

Variant swatch colors and images live on a shop metafield, not on each product. In theme Liquid, read shop.metafields['app--4638357--pl_swatches'].options.

The public copy, pl_swatches.options, has the same payload. Color Swatches writes it only while Enable public metafields is on (see enabling public metafields).

Payload structure

The value is one JSON object for the whole shop, keyed by option name:

{
  "Color": {
    "swatch_style": "color_or_image",
    "values": {
      "Black": {
        "type": "one_color",
        "color_one": "#000000",
        "color_two": null,
        "image": null
      },
      "Navy/White": {
        "type": "two_colors",
        "color_one": "#001F3F",
        "color_two": "#FFFFFF",
        "image": null
      }
    },
    "_lookup": {
      "Noir": "Black"
    }
  },
  "Size": {
    "swatch_style": "button",
    "values": {},
    "_lookup": {}
  },
  "_name_lookup": {
    "color": "Color",
    "couleur": "Color",
    "size": "Size"
  }
}

Keys that start with _ are lookups, not options. Skip them when you iterate.

Option fields

Field	What it is
swatch_style	How the option should render: color_or_image, button, or variant_image
values	Map of option value name to swatch visuals. Filled only when swatch_style is color_or_image
_lookup	Translated or alternate value names pointing at the canonical value name
sections	Optional. Labeled groups of values when variant sections are on

Value fields (color_or_image only)

Field	What it is
type	one_color, two_colors, or custom_image
color_one	Hex color (when type is one_color or two_colors)
color_two	Second hex color (when type is two_colors)
image	Image URL (when type is custom_image)

Swatch styles

• color_or_image - Use the values map for colors and custom images.
• button - values is empty. Render Shopify’s option values as text pills.
• variant_image - values is empty. Use each variant’s image from Shopify.

Joining to variants

This metafield does not include variant IDs, prices, or inventory. Shopify already has those. Fetch the product’s options and variants, then look up each name in the dictionary.

1. Lowercase the Shopify option name and resolve it through _name_lookup (covers translations).
2. On that option, take the Shopify value name. Use values[name] if it exists; otherwise resolve through _lookup.
3. Render from swatch_style and the matched value object.

The dictionary is shop-wide. Ignore entries that are not on the current product. For markets and unpublished variants, trust the product payload Shopify returns, not the full dictionary.

Reading from the Shopify Admin API

With public metafields on, any app that can query the Shop object can read pl_swatches.options. No Color Swatches API token is required.

query VariantSwatches {
  shop {
    variantSwatches: metafield(namespace: "pl_swatches", key: "options") {
      value
    }
  }
}

The value is a JSON string. Parse it, then join it to the product:

query ProductOptions($id: ID!) {
  product(id: $id) {
    options {
      name
      optionValues {
        name
      }
    }
    variants(first: 2048) {
      nodes {
        id
        selectedOptions {
          name
          value
        }
        image {
          url
        }
      }
    }
  }
}

The Shopify Storefront API cannot read pl_swatches.options: there is no shop metafield definition with storefront access. Use Admin GraphQL or Liquid.