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/. All five 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.
`templates`	Metadata for member templates and their dependencies. Template content stays in separate files.
`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 or template metadata overrides. 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": []
        }
      ]
    }
  ],
  "templates": [],
  "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; `null` uses the normal layout fallback. `"none"` opts out of a theme layout.
`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.

Rules use country codes such as US and CA, and member-type slugs such as customer and rep. Fluid resolves them against the receiving company. A missing country or missing/archived member type rejects the upload; it does not silently clear the restriction. 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; 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"
}

A non-null template reference must resolve. Listing a path does not create the file’s content. Preserve its exported template metadata and dependencies 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. Fluid can create a new menu and allocate a different handle on a collision.
country_codes must contain at least one country available in the receiving company. Unlike a site’s country rule, this cannot be empty.
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. Declared menu settings are rewritten to the allocated handle. Avoid hardcoding a handle that must survive a cross-company import.

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. Keep the templates and menu_references entries produced by a pull or export when editing navigation. They preserve template behavior and selected menus across imports. A templates entry requires these fields:

Field	Meaning
`path`	Relative member template or dependency path.
`status`	Template status from the exported theme. Preserve it unless intentionally changing template state.
`default`	Boolean marking the default template for its type.
`head`	Head content, including an empty string, or `null`.
`translations`	Exported translations object.
`format`	`"liquid"` or `"json"`.
`static_content`	Boolean retaining the template’s static-content setting.
`hide_navbar`	Boolean retaining the template’s navbar setting.
`use_active_application_theme`	Boolean retaining its active-theme setting.

These entries carry metadata, not Liquid bodies. Keep the separate template, layout, section, snippet, and settings files they depend on. Only templates belonging to the member composition can be declared here. 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": [],
  "templates": [],
  "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 after adding a country or member type	Use codes and slugs available in the target company. Do not use database IDs.
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.

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, template metadata, and menu references.
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.

Get Started

Core Concepts

Guides

Migration guides

Website & Themes

FairShare SDK

Files SDK

Portal & Widgets

Member sites manifest

Edit navigation with theme dev

Document structure

Example: a customer menu

Sites and access rules

Custom pages

Menus and nested items

Link targets

Template metadata 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

​Link targets

​Template metadata 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

Link targets

Template metadata and menu settings

Upload, import, and removal behavior

Troubleshooting

Task brief for coding agents