Medusa SDK

Extended Medusa JS SDK with support for a set of custom plugins. If you don’t use these plugins, you probably want the official @medusajs/js-sdk package instead.

Drop-in replacement for @medusajs/js-sdk that adds typed methods for Reviews, Content, Forms, and Analytics alongside all core Medusa storefront functionality. (No Admin functionality.)

Installation

yarn add "medusa-js-sdk"

Setup

import Medusa from 'medusa-js-sdk'

const sdk = new Medusa({
  baseUrl: 'http://localhost:9000',
  publishableKey: 'pk_...',
  auth: {
    type: 'session'
  }
})

All configuration options from @medusajs/js-sdk are supported.

Store

All core store methods from @medusajs/js-sdk are available unchanged:

const regions = await sdk.store.region.list()
const cart = await sdk.store.cart.create({})
const products = await sdk.store.product.list()

Reviews

// List approved reviews for a product
const { reviews, count } = await sdk.store.review.list('prod_123')

// Submit a review (requires customer authentication)
const { review } = await sdk.store.review.create('prod_123', {
  rating: 5,
  body: 'Excellent quality',
  author_name: 'Alice',
  author_email: '[email protected]'
})

Content

// List content collections
const { content_collections } = await sdk.store.content.list()

// Get a specific collection
const { content_collection } = await sdk.store.content.retrieve('blog')

// List published items in a collection
const { content_items } = await sdk.store.content.listItems('blog', {
  tag: 'announcements',
  limit: 10
})

// Get a specific content item
const { content_item } = await sdk.store.content.retrieveItem('blog', 'hello-world')

Forms

// Submit a form
const { submitted } = await sdk.store.form.submit('contact', {
  data: {
    name: 'Alice',
    email: '[email protected]',
    message: 'Hello!'
  },
  cf_turnstile_response: 'token...' // optional, if Turnstile is enabled
})

Products (Expanded Types)

sdk.store.product.list() and sdk.store.product.retrieve() return an expanded StoreProduct type that includes review data when the reviews plugin is installed:

const { products } = await sdk.store.product.list()

// products[0].reviews       — Review[]
// products[0].review_stats  — { average_rating: number, count: number }

Admin

All core admin methods from @medusajs/js-sdk are available unchanged:

const { orders } = await sdk.admin.order.list()
const { products } = await sdk.admin.product.list()

Reviews

// List reviews with filtering
const { reviews } = await sdk.admin.review.list({
  status: 'pending',
  product_id: 'prod_123'
})

// Get a single review
const { review } = await sdk.admin.review.retrieve('rev_123')

// Update a review
await sdk.admin.review.update('rev_123', { status: 'approved' })

// Delete a review
await sdk.admin.review.delete('rev_123')

// Bulk approve/reject
await sdk.admin.review.approve(['rev_123', 'rev_456'])
await sdk.admin.review.reject(['rev_789'])

Analytics

Privacy-focused event tracking for medusa-plugin-analytics. Events are batched and delivered to the backend’s /store/ping endpoint (one event or an array). Sales-channel attribution is derived server-side from the publishable key, and events are gated by the rubrics you define — so you only collect what you’ve configured.

There are three pieces, lowest- to highest-level.

store.analytics.track — stateless primitive

Send one event or a batch straight to /store/ping. Use it server-side, or as the building block behind the collector and framework forwarders.

await sdk.store.analytics.track([
  { event: 'page_view', actor_id: 'cart_123', properties: { path: '/' } },
  { event: 'product_viewed', actor_id: 'cart_123', properties: { product_id: 'prod_1' } }
])

createAnalyticsCollector — browser batcher (recommended)

A framework-agnostic client-side batcher: it queues events and flushes them in batches to a same-origin endpoint — normal flushes via fetch, exit events via sendBeacon. That endpoint is a small route in your app that forwards to Medusa with the publishable key and stamps identity (actor_id) from a server-managed anonymous_id cookie.

Why a same-origin endpoint instead of hitting Medusa directly? sendBeacon (needed to capture events as the tab closes) can’t attach the publishable-key header, and the backend may not even be reachable from the browser. Routing through your own origin solves both, keeps the key server-side, and lets the server own identity — a stable anonymous id that survives across carts and orders (unlike a cart id, which is cleared on order completion), and that the client can’t spoof.

import { createAnalyticsCollector } from 'medusa-js-sdk'

const analytics = createAnalyticsCollector({
  endpoint: '/api/analytics' // same-origin forwarding route (default)
})

analytics.track('product_viewed', { properties: { product_id: 'prod_1' } })
analytics.setTraits({ plan_interest: 'pro' }) // attach traits to the visitor's identity
// await analytics.flush()
// await analytics.destroy()   // flush + stop timers/handlers (on teardown)

Config: { endpoint?, batchSize?, flushInterval? } (defaults: /api/analytics, 10, 2000ms). The collector is self-managing — it starts its own timer and unload handler, so it works without any UI component. It never sends actor_id; the endpoint stamps it.

Example: Next.js (App Router)

Give every visitor a stable anonymous id (middleware — runs on first request):

middleware.ts

import { NextResponse } from 'next/server'
export function middleware(req) {
  const res = NextResponse.next()
  if (!req.cookies.get('aid')) {
    res.cookies.set('aid', crypto.randomUUID(), {
      httpOnly: true,
      sameSite: 'lax',
      secure: true,
      path: '/',
      maxAge: 60 * 60 * 24 * 365
    })
  }
  return res
}

The forwarding route (server — has the key; stamps actor_id from the cookie):

app/api/analytics/route.ts

import { cookies } from 'next/headers'
import Medusa from 'medusa-js-sdk'

const medusa = new Medusa({
  baseUrl: process.env.MEDUSA_BACKEND_URL!,
  publishableKey: process.env.MEDUSA_PUBLISHABLE_KEY!
})

export async function POST(req: Request) {
  const actor_id = (await cookies()).get('aid')?.value
  const body = await req.json()
  const events = (Array.isArray(body) ? body : [body]).map(e => ({ ...e, actor_id }))
  await medusa.store.analytics.track(events)
  return new Response(null, { status: 202 })
}

A client provider that mounts the collector:

app/analytics-provider.tsx

'use client'
import { createContext, useContext, useRef, useEffect } from 'react'
import { createAnalyticsCollector } from 'medusa-js-sdk'

const Ctx = createContext<ReturnType<typeof createAnalyticsCollector> | null>(null)
export const useAnalytics = () => useContext(Ctx)!

export function AnalyticsProvider({ children }) {
  const ref = useRef()
  ref.current ??= createAnalyticsCollector({ endpoint: '/api/analytics' })
  useEffect(() => () => ref.current.destroy(), [])
  return <Ctx.Provider value={ref.current}>{children}</Ctx.Provider>
}

// app/layout.tsx → <AnalyticsProvider>{children}</AnalyticsProvider>
// any client component → useAnalytics().track('product_viewed', { properties: { id } })

Using SvelteKit? sveltekit-medusa-sdk ships a ready-made <Analytics> component and forwarder, so you skip both files above.

Authentication

Authentication works exactly like @medusajs/js-sdk:

// Customer login
await sdk.auth.login('customer', 'emailpass', {
  email: '[email protected]',
  password: 'password'
})

// Customer registration
await sdk.auth.register('customer', 'emailpass', {
  email: '[email protected]',
  password: 'password'
})

// Logout
await sdk.auth.logout()

Raw Client

For endpoints not covered by the SDK, use sdk.client.fetch():

const result = await sdk.client.fetch('/admin/custom-endpoint', {
  method: 'POST',
  body: { key: 'value' }
})

Types

All types are exported for use in your application:

import type {
  // Custom plugin types
  Review,
  StoreCreateReviewInput,
  ContentCollection,
  ContentItem,
  FormSubmitInput,
  TrackOptions,

  // Expanded core types
  StoreProduct,
  AdminProduct,

  // SDK config types
  MedusaConfig,
  Config,
  ClientHeaders
} from 'medusa-js-sdk'