M

Medusa

Name: Medusa
Author: Finbaze

Finbaze Medusa plugin: tax quoting, product sync, and sales invoice order sync.

Featured on Medusa

npm install @finbaze/medusa

@finbaze/medusa

Medusa v2 plugin that connects a merchant store to Finbaze:

Tax Module Provider — checkout tax lines via Finbaze (profile obligations + imported products)
Product sync — Medusa variants → Finbaze products ( by , HS → )
Order sync — Shopify-parity invoices: draft on place/update, close+send when fulfilled, historical close without send, cancel/refund credits. Invoice is left empty (Finbaze assigns on close); Medusa goes in . Amounts are converted from Medusa major units to Finbaze minor units.

Install

In your Medusa application:

1npm install @finbaze/medusa
2pnpm add @finbaze/medusa
3# or, from this monorepo during development:
4# npx medusa plugin:add @finbaze/medusa
5# pnpm exec medusa plugin:add @finbaze/medusa

1import { defineConfig } from "@medusajs/framework/utils"
2
3module.exports = defineConfig({
// ...
plugins: [
  {
    resolve: "@finbaze/medusa",
    options: {
      storeKey: process.env.FINBAZE_STORE_KEY || "default",
      // Optional — public/OSS installs use PKCE only (omit secret)
      clientSecret: process.env.FINBAZE_APP_CLIENT_SECRET,
      backendUrl: process.env.MEDUSA_BACKEND_URL,
    },
  },
],
modules: [
  {
    resolve: "@medusajs/medusa/tax",
    options: {
      providers: [
        {
          resolve: "@finbaze/medusa/providers/finbaze-tax",
          id: "finbaze",
          options: {
            storeKey: process.env.FINBAZE_STORE_KEY || "default",
          },
        },
      ],
    },
  },
],
32})

Then migrate:

1npx medusa db:migrate
2pnpm exec medusa db:migrate

Assign each tax region that should use Finbaze to provider id (Medusa stores providers as ).

Environment

See .

, , and default to production (, , ). Override only for local Finbaze or a custom client.

Variable	Purpose
	Public Medusa URL for OAuth callback
	Logical store key for link tables
	Optional. Only for client-credentials refresh on hosted installs

Public / open-source installs (no client secret)

OAuth uses PKCE ( + ). You do not need a published .

Minimum env:

MEDUSA_BACKEND_URL=https://your-medusa.example.com

When the access token expires without a secret configured, reconnect via Admin (no silent client_credentials refresh).

OAuth redirect URI (seeded on ):

(or )

Admin

Open Finbaze in Medusa Admin ():

Connect Finbaze — PKCE OAuth against (public client: no secret)
Sync products — one Finbaze product per Medusa variant + (prices via Query / Pricing Module)
Import historical orders — draft/close with when fulfilled
Imported invoices () — paginated list of synced orders (Shopify-parity)
Settings () — after disconnect, Clear local DB links wipes Medusa-side / / credits / cursors / connection (debug only; does not delete Finbaze data)

Product / variant mapping

Finbaze has no variant entity: each Medusa variant becomes its own Finbaze product (SKU, EAN, prices). stores both (unique) and (tax fallback when Medusa only passes ).

Product HS metadata

On Medusa products (or variants), set metadata:

or

On first create of each variant, the plugin calls for the profile’s sell-to countries.

Tax quote contract

1query quoteSalesTax($profileId: ID!, $input: QuoteSalesTaxInput!): QuoteSalesTaxResult!
2
3input QuoteSalesTaxInput {
4  destinationCountry: String!
5  customerVatNumber: String
6  lines: [QuoteSalesTaxLineInput!]!
7}
8
9input QuoteSalesTaxLineInput {
10  externalLineId: String!
11  productId: ID
12  hsCode: String
13  quantity: Float
14  unitPriceMinor: Float
15  currency: String
16  isShipping: Boolean
17}

Auth: for quote; for product CRUD
Shipping lines are sent with
Item lines map Medusa → Finbaze via (tax provider falls back to when variant is unavailable)

Lifecycle (orders)

Event	Behavior
/	Create/update draft sales invoice (+ on lines when linked)
Fulfillment / completed
Historical import + fulfilled	Close with
	Credit closed invoice / delete draft
Refund	Credit invoice +

Package layout

1integrations/medusa/
src/
  modules/finbaze/     # FinbazeLink, ProductLink, OrderLink, OrderCreditLink, SyncCursor
  providers/finbaze-tax/
  lib/                 # finbaze-client, product-sync, order-sync, invoice-lines
  subscribers/
  api/admin/finbaze/          # status, sync, invoices list
  admin/routes/finbaze/       # setup + nested Imported invoices

Development (this repo)

1# From the monorepo root (preferred):
2pnpm install
3pnpm --filter @finbaze/medusa run dev
4
5# Or from this package:
6cd integrations/medusa
7pnpm install
8pnpm exec medusa plugin:develop