Sanity plugin for simple ecommerce with Stripe integration
npm install sanity-plugin-simple-commerceA Sanity v3 plugin for simple ecommerce with Stripe integration.
``bash`
npm install sanity-plugin-simple-commerce
For projects before npm publication, install directly from GitHub:
`json`
{
"dependencies": {
"sanity-plugin-simple-commerce": "github:cn-d/simple-commerce"
}
}
Then run npm install.
`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'
}),
],
})
`
| 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 |
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.
- Product - Product catalog with variant support
- Order - Order management with status tracking
- 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
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
`
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',
})
`
`typescript`
import type {
Product,
ProductVariant,
Order,
OrderItem,
ShippingAddress,
} from 'sanity-plugin-simple-commerce'
- Integration Guide - Stripe webhooks, order creation, stock management
- Limitations - Known constraints and trade-offs
- Security - Webhook-based dispatch email setup
- Technical Brief - Full specification
See CONTRIBUTING.md for detailed development workflow.
`bashInstall dependencies
npm install
$3
When developing the plugin alongside a project that uses it:
`bash
In this plugin directory
yalc publishIn your project directory
yalc link sanity-plugin-simple-commerce
`This creates a local override without changing the project's
package.json`.MIT