Square + Medusa.js Integration
The only published bidirectional Square integration for Medusa v2. Catalog sync, inventory, payments (Apple Pay, Google Pay), OAuth, and an admin UI extension — in one npm package.
Everything the medusa-square-plugin Handles
Products, variants, prices, and inventory sync between Square and Medusa in both directions. Square catalog changes propagate to Medusa via webhooks. Medusa catalog changes push to Square via the Catalog API. Conflict resolution is configurable.
Square Web Payments SDK integrated into Medusa checkout. Card payments, Apple Pay, and Google Pay all handled through Square — single integration, all payment methods. Payment confirmation creates the Medusa order automatically.
Merchants connect their Square account via OAuth directly in the Medusa admin panel. The admin UI extension shows connection status, sync health, and allows manual re-sync — no engineering required for ongoing operations.
Plugin Architecture Details
Medusa v2 Module Pattern
The plugin follows Medusa v2 module conventions: MedusaService pattern, StepResponse in workflows, subscriber idempotency. It extends Medusa correctly — no core modifications, full upgrade compatibility.
Square OAuth Flow
The plugin implements Square OAuth at the Medusa service level. Merchants authorize via Square's OAuth flow; the access token is stored in GCP Secret Manager (not in the database). The plugin handles token refresh automatically.
Webhook Processing
Square webhooks for catalog updates, inventory changes, and order events are processed by a dedicated Cloud Run microservice. The microservice validates HMAC signatures, deduplicates, and forwards verified events to Medusa subscribers.
Multi-Tenant Support
The plugin supports multiple Square merchant accounts in a single Medusa instance — required for marketplace architectures where each vendor has their own Square OAuth connection.
Admin UI Extension
A Medusa admin panel extension built with @medusajs/ui and @tanstack/react-query. Shows Square connection status, sync queue depth, last sync timestamp, and allows manual re-sync per entity type.
Frequently Asked Questions
Common questions about medusa-square-plugin.
Get Integration Support
Tell us your Medusa version, Square setup, and what you need the plugin to cover.
Published on npm
Install with npm install @weareseeed/medusa-square-plugin.
Medusa v2 module pattern
No core modifications, full upgrade compatibility.
Apple Pay + Google Pay included
All Square Web Payments SDK methods covered.
Seeed maintains it
Ongoing updates as Square and Medusa APIs evolve.
Get Integration Support
Tell us your Medusa version, Square setup, and what you need the plugin to cover.
Published on npm
Install with npm install @weareseeed/medusa-square-plugin.
Medusa v2 module pattern
No core modifications, full upgrade compatibility.
Apple Pay + Google Pay included
All Square Web Payments SDK methods covered.
Seeed maintains it
Ongoing updates as Square and Medusa APIs evolve.
