sanity-plugin-simple-commerce

A Sanity v3 plugin for simple ecommerce with Stripe integration.

Installation

$3

``bash
npm install sanity-plugin-simple-commerce
`

$3

For projects before npm publication, install directly from GitHub:

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

Then run npm install.

Usage

`typescript
// 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 |

$3

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

$3

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

$3

- 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

$3

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

`typescript
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
`

$3

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

`typescript
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',
})
`

$3

`typescript
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.

$3

`bash


Install dependencies

npm install

Build

npm run build

Watch mode

npm run watch

Link to test project with yalc

npm run link-watch
`

$3

When developing the plugin alongside a project that uses it:

`bash


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