sanity-plugin-simple-commerce

A Sanity v3 plugin for simple ecommerce with Stripe integration.

Installation

From npm (once published)

npm install sanity-plugin-simple-commerce

From GitHub

For projects before npm publication, install directly from GitHub:

{
  "dependencies": {
    "sanity-plugin-simple-commerce": "github:cn-d/simple-commerce"
  }
}

Then run npm install.

Usage

// sanity.config.ts
import { defineConfig } from 'sanity'
import { simpleCommerce } from 'sanity-plugin-simple-commerce'

export default defineConfig({
  // ...
  plugins: [
    simpleCommerce({
      prefix: 'STORE',      // Prefix for SKUs and order IDs
      currency: 'GBP',      // 'GBP' | 'USD' | 'EUR'
    }),
  ],
})

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | prefix | string | required | Prefix for SKUs and order IDs | | currency | 'GBP' \| 'USD' \| 'EUR' | 'GBP' | Currency for price display | | priceValidation | object | { minPrice: 0 } | Price validation rules (minPrice, maxPrice) | | orderFields | object | { trackingUrl: true, trackingCode: true, dispatchedAt: true } | Optional order fields | | maxVariantsWarning | number | 50 | Show warning when variants exceed this count |

Price Format

All prices are stored in the smallest currency unit (pence for GBP, cents for USD/EUR). This matches Stripe's unit_amount format directly, so no conversion is needed when creating checkout sessions.

For example, to set a price of £29.99, enter 2999 in Sanity Studio.

What's Included

Schemas

• Product - Product catalog with variant support
• Order - Order management with status tracking

Document Actions

• Generate Variants - Auto-generate variant combinations from options
• Dispatch Order - Mark order as dispatched (triggers webhook for email)
• Retry Dispatch Email - Re-trigger webhook if dispatch email failed
• Clear Dispatch Pending - Recovery action when webhook fails to clear pending state

GROQ Queries

Import queries from the /queries subpath. This is a lightweight import that works in Next.js Server Components without pulling in React dependencies.

import { queries } from 'sanity-plugin-simple-commerce/queries'

// Available queries:
// - queries.PRODUCTS_LIST
// - queries.PRODUCT_BY_SLUG
// - queries.ORDER_BY_ID
// - queries.VARIANT_STOCK
// - queries.VARIANT_WITH_PRICE
// - queries.PRODUCT_ID_BY_SLUG
// - queries.PENDING_ORDERS
// - queries.DISPATCHED_ORDERS

Helper Functions

Import helpers from the /helpers subpath for use in API routes and webhooks.

import {
  createOrderDocument,
  decrementVariantStock,
  checkVariantStock,
  getProductBySku,
} from 'sanity-plugin-simple-commerce/helpers'

// Create order from Stripe checkout session (use in webhook)
const order = await createOrderDocument({
  client: sanityClient,
  session: stripeCheckoutSession,
  prefix: 'STORE',
})

// Decrement stock with automatic retry on concurrent modification
const result = await decrementVariantStock({
  client: sanityClient,
  slug: 'product-slug',
  sku: 'SKU-123',
  maxRetries: 3, // default: 3, with exponential backoff
})
if (!result.success) {
  console.error(result.error)
} else {
  console.log(`Updated in ${result.attempts} attempt(s)`)
}

// Check stock availability
const { available, stock } = await checkVariantStock({
  client: sanityClient,
  slug: 'product-slug',
  sku: 'SKU-123',
})

Types

import type {
  Product,
  ProductVariant,
  Order,
  OrderItem,
  ShippingAddress,
} from 'sanity-plugin-simple-commerce'

Documentation

• Integration Guide - Stripe webhooks, order creation, stock management
• Limitations - Known constraints and trade-offs
• Security - Webhook-based dispatch email setup
• Technical Brief - Full specification

Development

See CONTRIBUTING.md for detailed development workflow.

Quick Start

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Link to test project with yalc
npm run link-watch

Local Development with yalc

When developing the plugin alongside a project that uses it:

# In this plugin directory
yalc publish

# In your project directory
yalc link sanity-plugin-simple-commerce

This creates a local override without changing the project's package.json.

License

MIT