Merchant API

Open-source commerce backend. Connect your Stripe account, deploy to Cloudflare Workers, and start selling.

Quick Start

git clone https://github.com/withpluto/merchant
cd merchant && npm install

npx tsx scripts/init.ts

npm run dev

curl -X POST http://localhost:8787/v1/setup/stripe \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"stripe_secret_key":"sk_test_..."}'

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer <api_key>

Products

Products are top-level catalog items. Each product has variants with individual SKUs and prices.

{
  "items": [
    {
      "id": "prod_abc123",
      "title": "Classic Tee",
      "status": "active",
      "variants": [...]
    }
  ]
}

{
  "title": "Classic Tee",
  "description": "Premium cotton t-shirt"
}

Variants

Variants are purchasable SKUs with their own price and inventory.

{
  "sku": "TEE-BLK-M",
  "title": "Black / Medium",
  "price_cents": 2999
}

Inventory

Track stock per SKU. on_hand is total stock, reserved is held for pending checkouts, available is what can be sold.

{
  "items": [{
    "sku": "TEE-BLK-M",
    "on_hand": 100,
    "reserved": 5,
    "available": 95
  }]
}

{ "delta": 50, "reason": "restock" }

Carts

Shopping carts expire after 30 minutes. Public keys can create and modify carts.

{ "customer_email": "buyer@example.com" }

{
  "items": [
    { "sku": "TEE-BLK-M", "qty": 2 }
  ]
}

Checkout

Creates a Stripe Checkout Session. Redirect customer to the returned URL.

{
  "success_url": "https://site.com/thanks",
  "cancel_url": "https://site.com/cart"
}

{
  "checkout_url": "https://checkout.stripe.com/...",
  "stripe_checkout_session_id": "cs_..."
}

Orders

Orders are created automatically when Stripe payment completes. Admin key required.

{
  "id": "ord_abc123",
  "number": "ORD-00001",
  "status": "paid",
  "customer_email": "buyer@example.com",
  "amounts": {
    "total_cents": 5998,
    "currency": "USD"
  },
  "items": [...]
}

{ "amount_cents": 2999 }

{
  "customer_email": "test@example.com",
  "items": [{ "sku": "TEE-BLK-M", "qty": 1 }]
}

Images

Upload images to R2 storage. Max 5MB. Accepts JPEG, PNG, WebP, GIF.

{
  "url": "https://...",
  "key": "store_id/uuid.jpg"
}

Webhooks

Configure Stripe to send webhooks to /v1/webhooks/stripe.

stripe listen --forward-to localhost:8787/v1/webhooks/stripe

Errors

All errors return a consistent format with code and message.

{
  "error": {
    "code": "not_found",
    "message": "Product not found"
  }
}