Setting Manifold up from a Shopify store

Who this is for: a merchant whose business runs on a Shopify store and who has no other inventory system they are leaving. Their products, stock, customers and orders live in Shopify; Manifold becomes the back office behind the store.

If they also run Cin7 (or another ERP) beside Shopify, stop and use the manifold-shopify-and-cin7 skill instead: the order you connect things in matters there.

What the merchant needs ready

Owner or staff access to the Shopify admin with permission to install apps. Only they can approve the app.
A Manifold account, or ten minutes to make one. Installing the app from Shopify makes one for them if they have none.
The Manifold connector in this client (https://mcp.getmanifold.io/mcp). The manifold-onboarding skill, step 2, says how to connect it.

Never

Never ask for, read out or type a password, an API key, a Shopify access token or a card number. The Shopify install is approved in Shopify's own page; billing is started on Stripe's page or approved on Shopify's, never in this conversation.
Never install, uninstall or approve the app for them. You cannot, and an agent must not try: it is the merchant's consent.
Never decide go-live, the plan or who joins the team. Ask, and send them to the screen.
Never invent data. Everything here comes from the store.

1. The install (the merchant's step)

Ask the merchant to install Manifold on their store. Two ways, both theirs:

From the Manifold admin: https://admin.getmanifold.io/settings/setup?step=source. In "Where do your products and orders live today?" they pick Shopify, type the store's .myshopify.com address and approve the app in the Shopify admin it opens.
From Shopify: the Shopify App Store, search "Manifold", Install. A store with no Manifold account gets an organization made for it, and the merchant signs in from inside Shopify.

Wait until they say it is done. Then connect the Manifold connector if it is not connected, picking the organization the store joined.

2. Find the store

onboarding_get_status. A journey started by the install has the app:shopify step. If there is no journey, onboarding_start with source: "agent".
shopify_list_connections. Take the connection whose shopDomain is their store and check its status is connected. A pending store means the approval in Shopify did not finish: send them back to it.
shopify_list_catalog_targets for the connection. Its first row is the shop's base prices, in the shop's own currency.

3. The business profile

onboarding_set_profile: business name, country, timezone and the currency the store prices in (step 2's base-prices currency). Ask what you do not know: whether they sell retail, wholesale or both, whether they buy from suppliers, and channels (at least store, for the Shopify store). A currency that differs from the store's makes every price mapping refuse later (CatalogCurrencyMismatch).

4. Locations

Every Shopify location that holds stock must be bound to one Manifold location. A binding is fixed once made, so ask before each one.

shopify_list_store_locations. Each row says whether it is bound (locationId). Right after the install, the app reads the store's locations and pairs each with a Manifold location of the same name (the store's Main with Main). That takes a few seconds: if nothing is bound yet, wait half a minute and read again before binding anything.
For each unbound, active location, ask the merchant: is this Main (inventory_list_locations), or a place of its own? A new place is inventory_create_location first.
shopify_update_connection with locationMappings (shopifyLocationId, locationId, locationName): the whole set, every binding shopify_list_store_locations already shows plus the new ones they agreed. A binding left out counts as dropped.
Read shopify_list_store_locations again after a few seconds: the binding shows once the reading it started has run.

A 409 LocationBindingLocked means the call would move or drop a binding that is already made (usually one left out of the set). Read the locations again, send the whole set, and carry on.

5. Use the store as a template

shopify_import_from_store brings the store across by area. Mint one jobId (job_<uuid>) for the call and reuse it on any retry. Ask which areas they want:

catalogs: a Manifold catalog per Shopify catalog, then the store's products and variants (one SKU each, uppercased), their prices, and opening stock at the bound locations.
customers: the store's customers, and, where it sells B2B, its companies with their contacts and locations.
orders: orders placed before the store was connected. The ones that ended (fulfilled, refunded, cancelled) come across as history (fulfillment_list_historical_orders). The open ones become live orders, with only what is left to ship.

Turn order bridging on first if open orders should become live ones (§6): an open order is handed to the bridge only when the store bridges orders.

Follow the import with shopify_get_connection: its imports say where each area stands (running, completed or failed) and what it counted. Read it again every half a minute or so; an import has no status of its own for manifold_wait. The catalogs area names the product pull it started (pullId): manifold_wait on shopify_get_catalog_pull with that pullId until applied or failed. shopify_list_jobs lists the runs behind it all.

Variants without a SKU are skipped. If the merchant wants a preview first, or SKUs made from the product handle, use shopify_request_catalog_pull instead of the catalogs area (skuFallback: "handle", without applyImmediately). Wait for it to be previewed with shopify_get_catalog_pull, show them the summary, and shopify_apply_catalog_pull on their word.

6. Prices and orders flowing

Catalog mappings: which Manifold catalog prices which Shopify catalog. Read the targets with shopify_list_catalog_targets, and the Manifold catalogs with catalog_list_catalogs, then propose a mapping and set it, on the merchant's word, with shopify_update_connection (catalogMappings).
Order bridging: bridgeOrders: true on shopify_update_connection makes each new Shopify order a Manifold order. An order the bridge refused (an unknown SKU, usually) shows in shopify_list_unbridged_orders: fix the cause, then shopify_retry_order_bridge.

7. The rest of setup

Hand back to the manifold-onboarding skill from its step 5 for the checklist: the order pipeline (fulfillment_set_workflow), suppliers, the accounting basis, the opening stocktake, books, billing and team. For a Shopify merchant:

Billing depends on how the organization was made. There is no tool that reads it; Settings › Billing shows which, so ask the merchant what it says.
- The install made the organization (they had no Manifold account and installed from the Shopify App Store): billing is on their Shopify bill. The first 30 days are free with no plan. They approve the plan at Settings › Billing, which sends them to Shopify's page.
- They signed up on Manifold first (the website, then the setup walk or Settings › Sales channels): connecting the store does not move billing. They start the 60-day trial on a card at Settings › Billing, through Stripe, like any other organization.
- Either way it is theirs to do. Never approve a plan or start a trial for them.
The opening stocktake (inventory_start_stocktake, inventory_stocktake_sheet, inventory_record_stocktake_counts) counts what the store said it had. Go through what looks wrong with them.

What stays read-only until go-live

A new organization is read-only: nothing leaves Manifold. Orders, customers and stock still come in from Shopify. But no stock level, price, fulfilment or product is pushed to Shopify, and a push is refused with 409 ConnectionReadOnly (heldBy: "organization"). That is the safety net while they check Manifold against their store. There is no tool that reads the mode: the badge at the top of the admin shows it. Tell the merchant this when they ask why Shopify did not change.

Going live is the owner's or an admin's decision, typed in at Settings › General. It needs every stock SKU costed (the opening stocktake completes at go-live) and, for an organization billed through Shopify, a plan approved there (409 PlanRequiredToGoLive otherwise). From then, Manifold drives the store: stock at the next check, prices on the mapped catalogs. Ask them; never imply it has happened.

Done looks like

onboarding_get_status: app:shopify, products and locations done, the rest done or skipped on the merchant's word, billing started (a plan approved on Shopify, or the card trial).
shopify_list_store_locations: every active location bound.
inventory_list_items matches the store's products. shopify_list_unbridged_orders is empty.
The merchant knows they are read-only until they go live, and where that switch is.

When it goes wrong

| What you see | What it means | Next |
|---|---|---|
| shopify_list_connections is empty | The app is not installed in this organization, or the connector is connected to another one | Ask which organization they installed into; reconnect the connector there |
| 409 ConnectionNotConnected | The store is pending: Shopify's approval did not finish | The merchant reopens the app from the Shopify admin |
| 409 CatalogCurrencyMismatch | The Manifold catalog prices in another currency than the Shopify one | Map a catalog in the store's currency, or create one (catalog_create_catalog) |
| An import area failed | Shopify refused, or throttled the read | Read shopify_list_exchanges for the call; run shopify_import_from_store again under a new jobId for that area alone |
| Orders in shopify_list_unbridged_orders | A line names a SKU Manifold does not have | Import or create the SKU, then shopify_retry_order_bridge |
| 409 ConnectionReadOnly on a push | The organization is read-only | Expected until go-live; say so |