Etsy sync
Medusa v2 plugin to sync Medusa products to a personal Etsy shop account via the Etsy Open API v3.
npm install @jytextiles/medusa-plugin-etsy-sync
Category
Built by
Service
Version
0.1.6
Last updated
4 months ago
Monthly downloads
Loading downloads
@jytextiles/medusa-plugin-etsy-sync
A Medusa v2 plugin that syncs your Medusa products to a personal Etsy shop via the Etsy Open API v3. It handles the OAuth2 (PKCE) connect flow, draft-listing creation, listing updates, image uploads, and keeps a per-product sync record so you can publish to Etsy from the Medusa Admin.
Features
- OAuth2 PKCE connect flow — connect/disconnect an Etsy shop from Settings → Etsy in the Admin; tokens are stored and auto-refreshed.
- Product → Etsy sync — create draft listings, update them, and upload product images (single or bulk).
- Readiness checks — surfaces what's missing (shop connection, shipping profile, return policy, taxonomy) before you publish.
- Sync records — every sync is tracked per product with status and the remote Etsy listing id.
- Scheduled token refresh — a background job keeps the Etsy access token fresh so syncs don't fail mid-session.
Requirements
- Medusa 2.17.x
- Node.js >= 22
- An Etsy app (keystring + shared secret) from the Etsy developer portal
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 Etsy app's keystring (API key). | ||
| yes | Your Etsy app's shared secret. | ||
| no | OAuth callback URL. Must match your Etsy app's registered callback. | ||
| no | Space-separated Etsy OAuth scopes. |
Add the callback URL () to your Etsy app's allowed redirect URIs in the Etsy developer portal.
After installing, run your project's migrations so the plugin's tables are created:
npx medusa db:migrateUsage
- In the Admin, go to Settings → Etsy and click Connect to authorize your Etsy shop.
- Configure your sync settings (shipping profile, return policy, taxonomy).
- From a product page, use the Etsy widget to sync the product, or sync in bulk from the Etsy settings page.
Admin API routes
| Method | Route | Purpose |
|---|---|---|
| GET | Connection + readiness status | |
| GET / POST | Read / save sync settings | |
| GET | Start the OAuth2 PKCE flow | |
| GET | OAuth2 callback | |
| POST | Disconnect the shop | |
| POST | Sync a single product | |
| POST | Sync multiple products | |
| GET | List sync records | |
| GET | Etsy taxonomy lookup | |
| GET | Etsy shipping profiles | |
| GET | Etsy return policies |