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 (OAuth 2.0). It handles the OAuth connect flow, product push (create/update + inventory), bulk product sync, bulk order ingestion, and inbound Faire webhooks for order/inventory/product events.

⚠️ Note on API specifics. Faire's developer portal is access-gated, so this plugin's endpoint paths, payload shapes and webhook signature scheme reflect the publicly documented v2 surface and standard OAuth2 conventions. If your Faire app uses a different base URL, token header, or signing scheme, override via the options/env vars below — the client is intentionally permissive. Verify against your Faire app's documentation before going live.

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).
• Faire → Medusa order ingestion — bulk-pull Faire orders and create matching Medusa orders (idempotent, payment marked captured).
• 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.
• Event-driven — inbound Faire webhooks (order placed/canceled/shipped, inventory updated, product updated) are verified, recorded idempotently and re-emitted as Medusa events; product.updated re-syncs linked products when their status actually changes.

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 the product, or sync in bulk from the Faire settings page (Bulk operations card).
4. Pull Faire orders into Medusa with the Start order pull button (also runs on a 30-minute schedule).

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