Etsy sync

@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

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

Configure

Register the plugin in medusa-config.ts:

1module.exports = defineConfig({
2  // ...
3  plugins: [
4    {
5      resolve: "@jytextiles/medusa-plugin-etsy-sync",
6      options: {
7        keystring: process.env.ETSY_KEYSTRING,
8        sharedSecret: process.env.ETSY_SHARED_SECRET,
9        redirectUri:
10          process.env.ETSY_REDIRECT_URI ??
11          "http://localhost:9000/app/settings/oauth/etsy/callback",
12        scope:
13          process.env.ETSY_SCOPE ?? "listings_r listings_w listings_d shops_r",
14      },
15    },
16  ],
17})

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

Add the callback URL (redirectUri) 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:migrate

Usage

1. In the Admin, go to Settings → Etsy and click Connect to authorize your Etsy shop.
2. Configure your sync settings (shipping profile, return policy, taxonomy).
3. From a product page, use the Etsy widget to sync the product, or sync in bulk from the Etsy settings page.

Admin API routes

Development

1# Build the plugin (compiles to .medusa/server)
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