Member sites manifest

Member storefront is in a limited pilot. Use a company with member storefront enabled and a current Fluid theme CLI that supports version 2 manifests.

members_sites.json is the portable member configuration at the theme root. It contains sites, access rules, page bindings, and complete navigation trees. Liquid, sections, layouts, and their settings remain in separate theme files. Use this file to change navigation from your editor or a coding agent such as Mist. You do not need to recreate the menu in the admin after each edit.

An upload is a complete snapshot, not a patch. Sites and pages omitted from the document are removed from the receiving theme. Start from the manifest pulled or exported from your theme, and preserve unrelated entries when editing one menu.

Start with your theme’s current files, including members_sites.json and its referenced templates.
Run fluid theme dev from the theme directory. By default, it creates or reuses an isolated development theme. --theme explicitly targets an existing theme; check the target before using it.
Find your site in sites. Follow its menu_key to the matching entry in menus.
Edit that menu’s items: change a title, update a target, reorder the array, or add nested children. Preserve every required field and keep keys unique.
Save the manifest. Wait for synced members_sites.json in the CLI output.
Check the CLI preview. With live reload enabled, it reloads after a successful upload and renders the updated menu.

The watcher submits the member document and its required local template dependencies together. Invalid member data or a missing dependency rejects the member upload, rather than applying only part of it. A concurrent remote edit can block the transfer; pull and reconcile the changes before retrying. Mist’s theme development workflow uses the same CLI watcher. An agent saving the file triggers the same upload as a manual edit. The CLI preview reloads automatically; a separately opened admin builder may need a refresh.

The layout must render the site’s menu, usually through settings.menu. Editing the manifest cannot change hardcoded navigation HTML. See Member sites for rendering behavior.

Document structure

Use the exact filename members_sites.json, including the s in members. Put it next to root-level variables.json, not inside config/. Fluid keeps config/members_sites.json for its own use, so an import that contains that file is rejected. These four top-level fields are required:

Field	Meaning
`version`	Integer `2`.
`sites`	Complete list of member sites and their custom pages.
`menus`	Full navigation trees used by those sites or declared menu settings.
`menu_references`	Links between menu settings in theme files and entries in `menus`.

Each object uses an exact set of fields. Include empty arrays, empty objects, or null where allowed; do not add your own fields. Document keys are portable references, not database IDs. Keep them stable while editing, but note that existing sites are matched by name, and pages by slug within their site. Changing a site name or page slug replaces that entry rather than performing an in-place rename. This complete example defines one customer site with two navigation links. It assumes the destination company has an active customer member type and the US country, and that layouts/member.liquid exists and renders settings.menu without additional selected menu settings. It has no custom pages. Use it as a format example. Do not replace an existing multi-site manifest with it to edit one link.

{
  "version": 2,
  "sites": [
    {
      "key": "customer-site",
      "name": "Customer",
      "active": true,
      "default": false,
      "position": 0,
      "layout_name": "member",
      "rule": {
        "country_codes": ["US"],
        "member_type_slugs": ["customer"]
      },
      "menu_key": "customer-menu",
      "pages": []
    }
  ],
  "menus": [
    {
      "key": "customer-menu",
      "handle": "customer-navigation",
      "title": "Customer navigation",
      "active": true,
      "country_codes": ["US"],
      "items": [
        {
          "key": "customer-shop",
          "title": "Shop",
          "titles": {},
          "target": { "type": "Shop" },
          "children": []
        },
        {
          "key": "customer-support",
          "title": "Contact support",
          "titles": {},
          "target": { "type": "Link", "url": "mailto:support@acme.com" },
          "children": []
        }
      ]
    }
  ],
  "menu_references": []
}

To rename Contact support to Get help, change that item’s title and save. If the item has translated labels in titles, update those labels too. To place it before Shop, move the whole item earlier in the items array.

Sites and access rules

Each site requires these fields:

Field	Meaning
`key`	Unique site reference within the document.
`name`	Unique site name within the theme; also used to match an existing site.
`active`	Boolean. Inactive sites do not match members.
`default`	Boolean. Marks a fallback site, considered after explicit sites. Use `false` for an ordinary audience-specific site.
`position`	Integer controlling site resolution order.
`layout_name`	Layout name without directory or extension, such as `member` for `layouts/member.liquid`. A name the theme doesn’t have falls back to `member`, then to `theme`. `null` starts at `member`. `"none"` renders no layout and never falls back.
`rule`	Object containing `country_codes` and `member_type_slugs` arrays.
`menu_key`	Key of an entry in `menus`, or `null` for no assigned menu.
`pages`	Array of custom member page definitions.

A rule has two keys: country_codes holds ISO country codes such as US and CA, and member_type_slugs holds member-type slugs such as customer and rep. Fluid resolves them when it imports the document, and neither case below clears a restriction:

Each entry in member_type_slugs must match exactly one active member type in the receiving company. Otherwise the upload or import fails with member type is missing or archived in destination, at that entry’s path. Before you copy a manifest to another company, check its slugs on the Member Types screen or with List company member types.
Fluid ignores a country code it doesn’t recognize. If none of a site’s country codes is recognized, the site is imported inactive, so it doesn’t widen to every country.

An empty rule axis is unconstrained. Clearing member_type_slugs broadens access; use active: false to disable a site. Country and member-type restrictions both apply when both are present. See Site access rules.

Custom pages

Every entry in a site’s pages array requires:

Field	Meaning
`key`	Page reference unique across all sites in this document.
`title`	Display title.
`slug`	Lowercase letters, numbers, and hyphens, or `/` for the site’s home page; unique within the site.
`published`	Boolean controlling whether the member page is published.
`template_path`	Relative path such as `members_page/rewards/index.liquid`, or `null` for an unbound page.

For example, add this object to the intended site’s pages array and include its template file in the theme:

{
  "key": "customer-rewards",
  "title": "Rewards",
  "slug": "rewards",
  "published": true,
  "template_path": "members_page/rewards/index.liquid"
}

Some slugs are reserved, because the account host serves its own routes at them: messaging, contacts, my-site, profile, orders, subscriptions, media, playlists, auth, api, and accounts. A page with one of these slugs fails with reserved system route. A non-null template reference must resolve. Listing a path does not create the file’s content. Include the layout, sections, snippets, and settings files that the page uses as well. System screens are Fluid-provided destinations. Link to them with a MembersScreen target; do not create custom page entries to represent them.

Menus and nested items

Each menu requires key, handle, title, active, country_codes, and items.

key connects the menu to sites and declared settings.
handle is the preferred menu slug. An unrelated existing menu with that slug is not a prerequisite. See Menu handles on import.
country_codes lists the countries the menu is available in. When it is empty, or none of its codes is recognized, the menu gets every country of the receiving company.
items is ordered. Each item requires key, title, titles, target, and children.
Item keys must be unique across all menus. titles maps locales to translated labels, such as {"en": "Shop", "fr": "Boutique"}. Use {} when there are no translations.
children contains more items of the same shape. Use [] for a leaf.

Every declared menu must be referenced by a site’s menu_key or a menu_references entry. Fluid preserves shared menus by creating a separate copy when an edit would otherwise change another consumer’s navigation. On import, Fluid updates the menu the site or setting already uses. When it has to create a menu and another menu in the company already has that handle, it adds a random suffix of 12 hexadecimal characters. For example, customer-navigation becomes customer-navigation-d4e420b8aada. Fluid rewrites two things to the handle it allocated:

Each site’s menu link, which the layout reads as settings.menu.
Each link_list setting listed in menu_references.

Fluid doesn’t rewrite a handle typed into Liquid, so that markup keeps pointing at the other menu that already had the handle. Read the site’s menu from settings.menu, or put the menu in a link_list setting, instead of naming a handle in markup.

Link targets

Destination	`target` shape
Custom member page	`{"type": "MembersPage", "site_key": "customer-site", "page_key": "customer-rewards"}`
System screen	`{"type": "MembersScreen", "key": "messaging"}`
Explicit URL	`{"type": "Link", "url": "https://acme.com/help"}`
Company content	`{"type": "Product", "handle": "starter-kit"}`
Built-in destination	`{"type": "Shop"}`

A MembersPage target must name a page belonging to the referenced site. A MembersScreen key must be a supported system screen, and the destination company must have the account screens runtime configured. Handle-based target types are Product, Medium, Page, EnrollmentPack, Collection, Post, and Library. Their content must already exist in the receiving company; the manifest does not transfer products or media. Built-in target types are HomePage, CollectionPage, CategoryPage, JoinPage, Shop, and PostPage. These take only type. Explicit links accept HTTP, HTTPS, mailto:, tel:, root-relative paths, and fragment links. Prefer MembersPage or MembersScreen targets for member destinations so Fluid resolves their routes. You do not need a templates array. New exports and pulls omit it, while the document version remains 2. Fluid resolves each custom page through its template_path and each site’s frame through layout_name. Referenced sections, blocks, and snippets stay in ordinary theme files; you do not maintain a second inventory in the manifest. For the Rewards page above and a site using layout_name: "member", keep these files together:

members_sites.json
layouts/member.liquid
members_page/rewards/index.liquid

Include any additional files referenced by that layout or page. A member page file can contain Liquid or a JSON object with a sections key; Fluid detects that format from the file contents. You do not need a manifest entry to declare the format. Changing only sites or navigation in the manifest preserves unrelated template settings and unpublished content. Uploading a template file applies that file’s changes. When you import files into a new theme, templates use normal import defaults for settings that the files do not carry. The manifest does not transport template-only flags or translations in a separate metadata list. Older version 2 manifests with a templates array are still accepted, including their template metadata. You can continue importing those files, but a new export or pull omits the array. Keep the menu_references entries produced by a pull or export when editing navigation. They connect selected menus in theme settings to the portable menu definitions. menu_references describes selected link_list settings. Each entry requires:

Field	Meaning
`path`	Theme file containing the setting.
`location`	`"json"` for JSON content or `"schema"` for a Liquid schema block.
`pointer`	JSON Pointer to the selected menu value within that JSON document or schema.
`menu_key`	Key of the menu in `menus`.

Every selected menu setting in the member composition needs exactly one matching reference. Use the references emitted by export or pull instead of guessing a pointer. If you add a new selected menu setting, add its reference and include the containing file.

Upload, import, and removal behavior

For a company theme, uploading the manifest updates that theme’s member configuration. Downloading it again reconstructs the document from the current sites, pages, menus, and templates.

Re-uploading unchanged configuration retains unchanged records.
Sites match by name; pages match by slug within their site. Document keys connect references within the file and are not persistent record identities.
Sites and pages omitted from a version 2 snapshot are removed. Removal can be rejected if a removed page is still referenced by another menu consumer.
Missing templates, unresolved content handles, invalid rules, and malformed documents reject the member upload.
Deleting or renaming members_sites.json is rejected. To intentionally clear the target theme’s member sites and pages, submit an explicit empty version 2 document. This is not a request to delete every company menu or theme file.

{
  "version": 2,
  "sites": [],
  "menus": [],
  "menu_references": []
}

Older array-based exports do not include a complete portable menu tree. Re-export or pull a version 2 document before editing navigation; a legacy menu_slug alone cannot reconstruct a menu in another company.

Troubleshooting

Symptom	What to check
Saving does not trigger an upload	Use the exact root filename `members_sites.json`, check `.fluidignore`, and confirm the CLI is watching this directory.
CLI says the member dependency is unavailable	Include all declared template files locally and remove ignore rules that exclude required dependencies.
Upload fails with `member type is missing or archived in destination`	Use a slug of an active member type in the target company, not a name or database ID.
An imported site serves nobody	None of its country codes was recognized, so it was imported inactive. Fix the codes and import again.
CLI reports an incomplete transfer	Correct the reported error and restart `fluid theme dev` as instructed. A rejected member transfer blocks later writes in that session.
Navigation stays unchanged after a successful upload	Check the CLI’s target theme, reload the correct preview, confirm the member resolves to the intended site, and verify the layout renders its assigned menu.
The admin builder still shows the previous menu	Refresh that builder. The CLI’s automatic reload applies to its own preview.
A menu handle changes after import	Fluid allocated a separate menu to avoid a collision or protect a shared menu. Use the site’s assigned menu or declared menu settings.
A member page shows another menu after import	The Liquid names the handle directly, and it now belongs to a different menu. Read `settings.menu` or a `link_list` setting instead.

Task brief for coding agents

Edit navigation for the Customer member site in this theme.
Read the existing members_sites.json first. Follow the site's menu_key to its menu.
Preserve all other sites, pages, menus, and menu references, along with their theme files.
Change only the requested menu labels, destinations, ordering, or children.
Keep keys unique and use portable targets instead of database IDs.
Save the complete manifest while fluid theme dev is running.
Wait for the successful sync message and inspect the CLI preview.
Report any upload error instead of claiming the preview changed.
Do not target or publish a live theme unless that action is authorized.

Start here

Building blocks

Storefront features

Advanced

Member storefront

Member sites manifest

Edit navigation with theme dev

Document structure

Example: a customer menu

Sites and access rules

Custom pages

Menus and nested items

Menu handles on import

Link targets

Template files and menu settings

Upload, import, and removal behavior

Troubleshooting

Task brief for coding agents

​Edit navigation with theme dev

​Document structure

​Example: a customer menu

​Sites and access rules

​Custom pages

​Menus and nested items

​Menu handles on import

​Link targets

​Template files and menu settings

​Upload, import, and removal behavior

​Troubleshooting

​Task brief for coding agents

Edit navigation with theme dev

Document structure

Example: a customer menu

Sites and access rules

Custom pages

Menus and nested items

Menu handles on import

Link targets

Template files and menu settings

Upload, import, and removal behavior

Troubleshooting

Task brief for coding agents