Faire store sync
Medusa v2 plugin to bidirectionally sync Medusa products, inventory and orders with a Faire brand account via the Faire External Platform API (OAuth 2.0).
@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 (), 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 () 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
Configure
Register the plugin in :
Options can be supplied via the object above or the matching environment variables (env takes precedence):
| Option | Env var | Required | Description |
|---|---|---|---|
| yes | Your Faire app's application id. | ||
| yes | Your Faire app's application secret. | ||
| no | OAuth callback URL. Must match your Faire app's registered redirect. | ||
| no | Override the Faire API base URL (e.g. for sandbox). | ||
| no | Override the OAuth authorize URL. | ||
| no | Override the OAuth token URL. |
After installing, run your project's migrations so the plugin's tables are created:
npx medusa db:migrateOptional behavior flags
| Env var | Default | Effect |
|---|---|---|
| Set to disable creating Medusa orders from Faire. | ||
| Set to decrement Medusa stock on Faire order ingest. | ||
| Set to disable the scheduled order-pull job. |
Usage
- In the Admin, go to Settings → Faire and click Connect to authorize your Faire brand.
- Configure sync settings (brand, wholesale markup %, shipping policy).
- 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.
- Pull Faire orders into Medusa with the Start order pull button (orders also pull automatically every 5 minutes).
Admin API routes
| Method | Route | Purpose |
|---|---|---|
| GET | Connection + readiness status | |
| GET/POST | Read / save sync settings | |
| GET | Start the OAuth2 flow | |
| POST | OAuth2 callback (called by the SPA) | |
| POST | Disconnect the brand | |
| POST | Sync a single product | |
| POST | Sync multiple products (background workflow, 202) | |
| GET | Poll bulk product-sync progress | |
| POST | Pull Faire orders (background workflow, 202) | |
| GET | Poll bulk order-ingest progress | |
| GET | List sync records | |
| GET/POST | Fetch / retry a sync record | |
| GET | The connected Faire brand | |
| GET | Products already on Faire |

