Faire store sync

@jytextiles/medusa-plugin-faire-store-sync

A Medusa v2 plugin that bidirectionally syncs your Medusa products, inventory and orders with a Faire brand account via the Faire External Platform API v2 (OAuth 2.0). It handles the OAuth connect flow, product push (create/update + inventory), bulk product sync, and scheduled order ingestion. Faire is polling-based — it exposes no inbound webhooks — so orders are pulled on a schedule using a cursor.

Features

• OAuth 2.0 redirect connect flow — connect/disconnect a Faire brand from Settings → Faire in the Admin; tokens are stored and auto-refreshed when applicable.
• Product → Faire sync — create/update Faire products, push variant inventory, upload images via URL (single or bulk).
• Bulk products page — a searchable/selectable table of your catalog (Settings → Faire → Bulk) to push many products to Faire in one job.
• Faire → Medusa order ingestion — pull Faire orders and create matching Medusa orders (idempotent, payment marked captured).
• Scheduled order polling — Faire has no webhooks, so orders are pulled on a schedule (every 5 minutes by default) using a cursor-based high-water mark (last_order_sync_at), fetching only orders changed since the previous run.
• Status-follow subscriber — when a synced product's Medusa status actually changes (e.g. draft → published), the linked Faire product is re-synced automatically. This is an internal Medusa event, hard-guarded to respect Faire's rate limits (only already-linked products, only on real status change).
• Readiness checks — surfaces what's missing (brand, wholesale-pricing strategy, shipping policy) before publishing.
• Sync records — every sync is tracked per product with status and the remote Faire product token.
• Long-running bulk workflows — both bulk product push and bulk order pull run as background workflows (backgroundExecution) with a pollable batch id.

Requirements

• Medusa 2.17.x
• Node.js >= 22
• A Faire app (client id + client secret) from the Faire developer portal, with the OAuth redirect URL registered.

Install

1npm install @jytextiles/medusa-plugin-faire-store-sync
2# or
3yarn add @jytextiles/medusa-plugin-faire-store-sync
4# or
5pnpm add @jytextiles/medusa-plugin-faire-store-sync

Configure

Register the plugin in medusa-config.ts:

1module.exports = defineConfig({
2  // ...
3  plugins: [
4    {
5      resolve: "@jytextiles/medusa-plugin-faire-store-sync",
6      options: {
7        clientId: process.env.FAIRE_APP_ID,
8        clientSecret: process.env.FAIRE_APP_SECRET,
9        redirectUri:
10          process.env.FAIRE_REDIRECT_URI ??
11          "http://localhost:9000/app/settings/oauth/faire/callback",
12        // Optional overrides (defaults shown):
13        // apiBase: "https://faire.com/external-api/v2",
14        // authUrl: "https://faire.com/oauth2/authorize",
15        // tokenUrl: "https://www.faire.com/api/external-api-oauth2/token",
16      },
17    },
18  ],
19})

Options can be supplied via the options object above or the matching environment variables (env takes precedence):

After installing, run your project's migrations so the plugin's tables are created:

npx medusa db:migrate

Optional behavior flags

Usage

1. In the Admin, go to Settings → Faire and click Connect to authorize your Faire brand.
2. Configure sync settings (brand, wholesale markup %, shipping policy).
3. From a product page, use the Faire Sync widget to sync a single product, or open the Bulk products page (Settings → Faire → Bulk) to select many products from a searchable table and push them in one background job.
4. Pull Faire orders into Medusa with the Start order pull button (orders also pull automatically every 5 minutes).

Admin API routes

Development

1# Build the plugin (compiles to .medusa/server, then restructures via postbuild)
2npm run build
3
4# Watch mode while developing against a local Medusa app
5npm run dev
6
7# Generate a migration after changing a model
8npm run db:generate
9
10# Run tests
11npm run test

License

MIT