Square plugin

@weareseeed/medusa-square-plugin

A full-featured Square integration plugin for Medusa v2. Handles payment processing, OAuth account linking, bidirectional catalog/customer/inventory sync, and Apple Pay domain registration — all configurable from the admin dashboard at runtime.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Admin UI
• Storefront Integration
• Data Synchronization
• API Reference
• Workflows
• Usage

Features

• OAuth 2.0 — Secure merchant account linking via Square OAuth with encrypted token storage and automatic refresh
• Payment Processing — Full authorize → capture → cancel → refund flow via AbstractPaymentProvider
• Location Support — List and select which Square location processes payments
• Bidirectional Sync — Sync products, categories, customers, and inventory between Medusa and Square
• Order Sync — Create Square orders from Medusa cart data at payment time
• Apple Pay — Register a domain for Apple Pay support
• Sandbox & Production — Toggle between environments without redeployment
• Database-driven Config — All settings stored in the database; no restart required after changes

Prerequisites

• Node.js >= 20
• Medusa v2.x (peer dependency)
• PostgreSQL (for plugin configuration table)
• Redis (recommended, for caching)
• A Square Account

Installation

Register in medusa-config.ts

No options are required. All configuration is managed through the Admin UI.

Run Migrations

npx medusa db:migrate

This creates the square_configuration table used by the plugin.

Configuration

Environment Variables

The OAuth callback will be registered at {MEDUSA_BACKEND_URL}/admin/square/oauth.

Admin UI

After installing, a Square section appears under your Medusa Admin settings. It has three tabs:

Account Tab

• Connect / Disconnect your Square account via OAuth
• Toggle between Sandbox and Production environments
• View linked account status
• List your Square locations and select which one processes payments

Apple Pay Tab

• Register your storefront domain for Apple Pay
• View the currently registered domain

Settings Tab

• Choose sync source of truth: Medusa or Square
• Orders (auto-created in Square at payment time)
• Toggle individual sync features:
  • Catalog (products and categories)
  • Customers
• Trigger a manual sync workflow
• Stop an in-progress sync

Storefront Integration

Use react-square-web-payments-sdk — the official React wrapper around the Square Web Payments SDK, built by the same team — to collect payment details on your storefront.

Install

Fetch Public Config

Before rendering the payment form, fetch the public Square config from the store endpoint to get the application_id and location_id:

GET /store/square/config

Response:

Basic Credit Card Form

Wrap your checkout with PaymentForm and drop in the CreditCard component. The SDK handles input rendering and tokenization.

Data Synchronization

The plugin supports bidirectional sync between Medusa and Square.

Automatic (Real-time)

Event subscribers listen for Medusa events and push updates to Square:

These run only when sync_catalog / sync_customers are enabled in the config.

Manual (Workflow-based)

Trigger from the Admin UI or programmatically:

Medusa → Square (sync-medusa-square-workflow)

• Syncs customers
• Syncs product categories
• Syncs products with images
• Syncs inventory levels per location

Square → Medusa (sync-square-medusa-workflow)

• Pulls catalog from Square
• Transforms and upserts products/categories into Medusa
• Updates inventory

Using Workflows Programmatically

API Reference

All routes are prefixed with your Medusa backend URL.

Admin Routes

Require admin authentication.

Store Routes

Public endpoints for storefront use.

Workflows

The plugin exports Medusa v2 workflows that can be composed into your own workflows:

Usage

Connect Your Square Account

1. Log in to your Medusa Admin dashboard
2. Navigate to Settings → Square
3. Toggle Sandbox on if you are testing, or leave it off for production
4. Click Connect Square Account — you will be redirected to Square's OAuth page
5. Authorize the connection — you are redirected back to the admin dashboard

Make sure MEDUSA_BACKEND_URL is set to your publicly accessible backend URL before starting the OAuth flow, otherwise the redirect will fail.

Select a Location

After connecting:

1. In the Account tab, your Square locations are listed automatically
2. Click a location row to set it as the active location for payment processing
3. The selected location ID is stored in the database and used for all subsequent payments

Configure Sync (Optional)

In the Settings tab:

1. Choose whether Medusa or Square is the source of truth for catalog data
2. Enable the sync features you need:
   • Sync Catalog — keeps products and categories in sync
   • Sync Customers — mirrors customer records to Square
3. Click Sync Now to run a full manual sync, or let the real-time subscribers handle incremental updates

Accept Payments on the Storefront

1. Install react-square-web-payments-sdk in your storefront (see Storefront Integration)
2. Fetch /store/square/config to get application_id, location_id, and currency
3. Render <PaymentForm> with <CreditCard /> (or another payment method component) at checkout
4. On tokenization, call initiatePaymentSession with provider_id: "pp_square_square" and pass token, buyer, and cart_id in the data field
5. Complete the cart — the plugin will authorize and capture the payment automatically

Register Apple Pay Domain (Optional)

1. In the Apple Pay tab, enter your storefront domain (e.g. store.yourdomain.com)
2. Click Register — the plugin calls Square's domain registration API and stores the domain
3. Download the Square's verification file
4. Make sure your storefront serves Square's domain verification file at /.well-known/apple-developer-merchantid-domain-association

Payment Status Mapping