Integration Module 2.0 for Medusa is outRead the announcement
Faire store sync logo

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).

npm install @jytextiles/medusa-plugin-faire-store-sync
Category
Built by
Service
Version
0.2.16
Last updated
4 months ago
Monthly downloads
Loading downloads

@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):

OptionEnv varRequiredDescription
yesYour Faire app's application id.
yesYour Faire app's application secret.
noOAuth callback URL. Must match your Faire app's registered redirect.
noOverride the Faire API base URL (e.g. for sandbox).
noOverride the OAuth authorize URL.
noOverride the OAuth token URL.

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

npx medusa db:migrate

Optional behavior flags

Env varDefaultEffect
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

  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

MethodRoutePurpose
GETConnection + readiness status
GET/POSTRead / save sync settings
GETStart the OAuth2 flow
POSTOAuth2 callback (called by the SPA)
POSTDisconnect the brand
POSTSync a single product
POSTSync multiple products (background workflow, 202)
GETPoll bulk product-sync progress
POSTPull Faire orders (background workflow, 202)
GETPoll bulk order-ingest progress
GETList sync records
GET/POSTFetch / retry a sync record
GETThe connected Faire brand
GETProducts already on Faire

Development

License

MIT