API Reference

The Sellforge REST API gives you programmatic access to everything you can do in the admin — orders, products, customers, inventory, accounting, marketplace, affiliates. Build integrations, custom reports, or replace the admin UI entirely.

Introduction

All requests use JSON bodies with Content-Type: application/json. All responses are JSON and use snake_case field names. Currency amounts are always integers in the smallest unit (cents), never floats. Dates are ISO-8601 in UTC.

The API is organized around resources grouped by domain (Orders, Products, Vendors, etc.). Most endpoints follow REST conventions: GET for read, POST to create, PATCH to update, DELETE to remove.

Authentication

All authenticated endpoints use JWT bearer tokens passed in the Authorization header. Tokens are issued via POST /api/auth/login and carry a role (admin, partner, vendor, affiliate, or customer) that gates which endpoints you can call.

// Request
curl -X POST https://api.sellforge.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"mara@shop.at","password":"…"}'

// Response
{
  "token": "eyJhbGciOiJIUzI1NiI…",
  "user": {
    "user_id": "usr_3kF92",
    "email": "mara@shop.at",
    "role": "admin"
  }
}

Using a token

// All authenticated requests
curl https://api.sellforge.ai/api/admin/orders \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiI…"

Two-factor authentication

2FA endpoints under /api/twofa/* let you enroll (TOTP setup with QR), verify, and disable 2FA for the current user. Enrollment generates 10 backup codes returned once at activation time.

Storefront public key (pk_sf_…)

The public Storefront API under /api/store/* (products, cart, checkout, order lookup) is addressed with a publishable key that identifies your shop. Generate and rotate it in your shop settings under Public API / Storefront-Key. Pass it in the Authorization header:

// Storefront request — the key selects your shop (tenant)
curl https://api.sellforge.ai/api/store/products \
  -H "Authorization: Bearer pk_sf_…"

The key is not a secret — it ships in your browser storefront and only exposes published, shop-scoped catalog/cart/checkout data. Each key is bound to exactly one shop, so it can never read another shop's data. Rotating a key invalidates the previous one immediately.

Domain allowlist (recommended for go-live): in the same settings screen you can restrict the key to your storefront domain(s). When set, requests from other origins are rejected with 403. Leaving it empty allows any origin — convenient during development, but set it before going live.

Errors

Sellforge uses standard HTTP status codes. Error responses share a common shape:

{
  "error": "validation_error",
  "message": "customer_email must be a valid email",
  "details": { "field": "customer_email" }
}

Pagination

List endpoints accept limit (default 50, max 200) and offset query parameters. The response always includes count (total matching), limit, and offset.

GET /api/admin/orders?limit=50&offset=0

{
  "orders": [ … ],
  "count": 1247,
  "limit": 50,
  "offset": 0
}

Rate limits

Authenticated endpoints allow 600 requests per minute per token. Public POST endpoints (registration, cooperation, review submission) are limited per IP. Limits are not yet enforced on read-only endpoints but may be in the future.

Idempotency

For endpoints that create resources with side-effects (place order, create invoice, send webhook), you can pass an Idempotency-Key header (any unique string up to 255 chars). If the same key is replayed within 24h, the original response is returned without re-executing the operation.

Versioning

The current API is v1 and is stable. Breaking changes require a new version path (/api/v2/…). Additive changes (new optional fields, new endpoints) ship to v1 without notice. The x-api-version response header indicates the version that served the request.

Orders

An order represents a customer purchase. Orders progress through pending → paid → shipped → completed with branches for cancelled and refunded. Each order automatically gets a SevDesk invoice on creation (if configured) and the invoice number appears in the Stripe PaymentIntent descriptor for auto-reconciliation.

Order object

{
  "id": "ord_8aG2k…",
  "display_id": 3812,
  "customer_id": "usr_3kF92",
  "customer_email": "anja.k@protonmail.com",
  "customer_name": "Anja Kovacs",
  "status": "paid",
  "source": "ONLINE",
  "subtotal_cents": 17700,
  "tax_cents": 3150,
  "shipping_cents": 1200,
  "discount_cents": 0,
  "total_cents": 18900,
  "currency": "EUR",
  "shipping_address": { … },
  "billing_address": { … },
  "stripe_payment_intent_id": "pi_3O…8aG",
  "tracking_number": "00340…0042",
  "tracking_url": "https://nolp.dhl…",
  "sevdesk_invoice_id": "sdi_4012",
  "sevdesk_invoice_number": "RE-2026-001247",
  "sevdesk_sync_status": "synced",
  "created_at": "2026-05-13T14:08:02Z",
  "paid_at": "2026-05-13T14:08:14Z"
}

{ "url": "https://r2.../invoices/2026/RE-2026-001247.pdf?X-Amz-Signature=…", "expires_in": 300 }

Customer-facing

Products

Products represent sellable items. Each product can have variants (size, color), media (images, PDFs), category, tax class, and per-vendor ownership. Types: STANDARD, ASSEMBLY (calculated from BOM), INTERNAL (not sellable, used in production).

{
  "name": "Cassette 11-46T",
  "slug": "cassette-11-46",
  "sku": "SLT-CAS-1146",
  "type": "STANDARD",
  "status": "published",
  "base_price_cents": 5900,
  "cost_price_cents": 2240,
  "tax_class_id": "tax_20",
  "weight_grams": 340
}

Customers

Customers can be registered users or guests (only email + addresses on the order). Lifecycle data, audit trail, and order history are tracked even for guests where possible.

Categories

Hierarchical product categories with arbitrary nesting depth.

Tax classes

Discounts

Discount codes with three types: fixed (cents off), percent, or free_shipping. Optional max uses, expiry, min order value.

Warehouses

Physical storage locations (and POS counters) with optional sub-locations (bin / shelf / aisle). Stock is tracked per warehouse-location, not per warehouse aggregate.

Inventory

POST /api/admin/inventory/adjust
{
  "variant_id": "var_8aG2k",
  "location_id": "loc_WH-AT-A3",
  "delta": -3,
  "reason": "DAMAGED",
  "notes": "Bent during pick"
}

Fulfillments

Pick-list-driven fulfillment workflow. An order becomes one or more fulfillments (when items split across warehouses). Each fulfillment moves through requested → picking → packed → shipped → delivered.

Returns

RMA workflow with explicit states: requested → approved → received → inspected → refunded (or rejected at any point).

Transfers

Internal stock movements between warehouses or locations.

Suppliers

Invoices

Customer-facing invoices. By default Sellforge uses SevDesk as the source of truth — invoices are created there and the PDF is archived in your R2 bucket. The endpoints below also support a built-in PDF generator (legacy / fallback when SevDesk is not configured).

Credit notes

SevDesk integration

SevDesk is wired in directly. On order creation, Sellforge creates a SevDesk contact (if needed), an invoice, and embeds the invoice number in the Stripe PaymentIntent descriptor (e.g. "Rechnung RE-2026-001247") so bank transactions auto-match in your SevDesk inbox.

Settings keys

Vendors

Marketplace mode. Vendors operate as sub-tenants with their own product catalog. Sellforge handles split payments via Stripe Connect, per-vendor earnings tracking, and ledger-style statements.

Admin endpoints

Vendor earnings

Vendor payouts

Vendor statements

Vendor self-service portal

Endpoints called by the vendor's own app. Requires role: "vendor" JWT.

Affiliates

Affiliate program with referral tracking. Affiliates earn a percentage on orders that originate from their tracked link (cookie + first-touch attribution, configurable window).

Admin endpoints

Earnings & payouts

Affiliate self-service portal

Production orders

For shops that manufacture their own goods (3D printing, assembly, etc.). A production order consumes raw materials, runs a process, and yields finished products that decrement BOM stock and increment finished-good stock.

Purchase orders

Settings & credentials

All app settings (Stripe, SevDesk, R2, Resend, Sendcloud credentials) live in a unified key-value table with optional encryption-at-rest for secrets. Changes are audit-logged and invalidate the relevant service-client caches automatically.

Jobs queue

Background job queue implemented in Postgres with FOR UPDATE SKIP LOCKED. Used for emails, invoice generation, SevDesk syncs, CSV imports.

Audit log

Append-only log of every mutation. Auto-derived category from action prefix (sevdesk.invoice.created → "sevdesk"). Filterable by user, action, category, entity type, entity ID.

{
  "entries": [{
    "id": "aud_8aG…",
    "action": "sevdesk.invoice.created",
    "category": "sevdesk",
    "entity_type": "orders",
    "entity_id": "ord_3812",
    "user_id": null,
    "metadata": { "invoice_number": "RE-2026-001247" },
    "created_at": "2026-05-13T14:08:22Z"
  }]
}

CSV import / export

RFC-4180-compliant CSV with UTF-8 BOM (Excel-safe). Imports run as background jobs with per-row error tracking. Exports stream directly.

{
  "id": "job_8aG…",
  "type": "csv.import.products",
  "status": "done",
  "progress": { "processed": 412, "total": 412 },
  "summary": {
    "total": 412,
    "created": 298,
    "updated": 112,
    "skipped": 2,
    "errors": [{ "row": 14, "field": "base_price_cents", "message": "Preis nicht parsbar" }]
  }
}

Media uploads

All image uploads go through Sharp pipeline → WebP variants (thumb 200×200 cover, small 480, medium 960, large 1600) + lossless WebP original. Animated GIFs preserved as animated WebP. Files stored in R2 (or local /static/uploads in dev).

Users & partners

CMS Pages

Simple page CMS for static content (Imprint, Privacy, About, blog posts). Markdown body + meta fields + draft/published state.

Newsletter & subscribers

Double-opt-in newsletter list, scoped to your shop. The same address can subscribe to several shops independently. Subscribers move through pending → active → unsubscribed (plus bounced).

Campaigns

A campaign is composed once and sent to an audience via the background job queue — one job per recipient, so it is retryable and never blocks the request. It renders either a built-in template (template_slug + content) or your own raw HTML body (see Custom emails). For opt-in recipients, open/click tracking and an unsubscribe link are added automatically.

Custom emails & attachments

Beyond the built-in templates, a campaign can carry a raw HTML body_html and file attachments, sent to one of three audiences. When body_html is set the template is ignored. The sender is the platform default address; an unsubscribe footer is appended automatically for opt-in subscribers only (free lists and “all customers” are sent as-is).

Audiences

The audience is stored on the campaign as audience_filter and resolved at send time (always scoped to your shop).

// custom HTML for a free email list, with one attachment
{
  "name": "Summer sale",
  "template_slug": "custom",
  "subject": "20% off this weekend",
  "body_html": "<h1>Summer sale</h1><p>20% off this weekend…</p>",
  "audience_filter": { "type": "list", "emails": ["a@example.com", "b@example.com"] },
  "attachments": [{ "key": "sellforge/tenant/…/documents/newsletter/att_…-flyer.pdf", "filename": "flyer.pdf", "size": 20480, "contentType": "application/pdf" }]
}

// Request body (only needed for all_customers)
{ "confirm_all_customers": true }

// Response
{ "ok": true, "recipients": 128, "audience": "list" }

// Response
{ "key": "sellforge/tenant/…/documents/newsletter/att_…-flyer.pdf", "filename": "flyer.pdf", "size": 20480, "contentType": "application/pdf" }

Public catalog

Read-only endpoints meant for the storefront frontend or any public consumer. No authentication required. Cache-friendly with Cache-Control: public, max-age=60.

Vehicle fitment

For shops with vehicle-specific products (motorcycle parts, bicycle parts). Tree: Make → Model → Year-Group → fitted products.

Shipping

Tracking

{
  "status": "in_transit",
  "carrier": "dhl",
  "events": [
    { "at": "2026-05-13T17:22Z", "location": "Wien Hub", "description": "Eingang im Versandzentrum" }
  ],
  "tracking_url": "https://nolp.dhl…"
}

Outgoing webhooks

Sellforge can deliver event webhooks to your server. Subscribe by configuring an endpoint URL + secret in /api/admin/settings. Events are signed with HMAC-SHA256 over the raw body using your endpoint secret. Retries: 5 attempts with exponential backoff.

Event format

POST https://your-server.example/webhooks/sellforge
X-Sellforge-Signature: t=1620000000,v1=5257a869…
X-Sellforge-Event-Id: evt_8aG2k…
Content-Type: application/json

{
  "id": "evt_8aG2k…",
  "type": "order.paid",
  "created_at": "2026-05-13T14:08:14Z",
  "data": { /* full order object */ }
}

Event types

Signature verification (Node.js example)

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const [ts, sig] = header.split(",").map(s => s.split("=")[1]);
  const payload = `${ts}.${rawBody}`;
  const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex");
  if (Math.abs(Date.now()/1000 - +ts) > 300) throw new Error("stale");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Incoming receivers

Endpoints where third-party services notify Sellforge. You shouldn't call these directly — they're listed for completeness.

Changelog

2026-07-26 — v1.5

• Custom email campaigns. Newsletter campaigns can now carry a raw HTML body_html and file attachments instead of only a built-in template. Send to a selectable audience (audience_filter.type): subscribers (newsletter opt-ins), list (a free email list), or all_customers (every registered customer — requires an explicit confirm_all_customers: true; obtaining consent stays the sender's responsibility). An unsubscribe footer is auto-appended for opt-in recipients only. New endpoint: POST /admin/newsletter/attachments (multipart → R2, max 10 MB). Sending is fan-out via the job queue (newsletter.send_custom_one); audit action newsletter.custom_send. See Custom emails & attachments.

2026-05-13 — v1.4

• SevDesk integration shipped. Auto-invoicing, R2 PDF archive (10-year retention, GoBD-ready), Stripe descriptor matching for auto-reconciliation, per-country tax-rule mapping, retry scheduler. New endpoints: /orders/:id/sevdesk-retry, /orders/:id/sevdesk-cancel, /orders/:id/invoice-url, /credentials/test/sevdesk.
• Cloudflare R2 native storage. Settings UI for credentials + bucket configuration. Helper: uploadInvoicePdfToR2. Public-bucket CDN URLs + presigned download URLs for private documents.
• Image pipeline: WebP-only. Originals re-encoded as lossless WebP. Animated GIF support preserved (animated WebP output). Disk-binary fallback removed.
• CSV import / export. Products, customers, orders. RFC-4180 with UTF-8 BOM. Slug-upsert (products), email-upsert (customers, optional invite mail). Job-queue-async with per-row error tracking. New routes under /admin/{entity}/{template,export,import}.csv + /admin/imports/:jobId/status.
• Audit log: categories + scopes. Auto-derived category from action prefix. Color-coded pills in admin UI. New filter ?category=. New endpoints: /admin/audit-log/categories, /admin/orders/:id/audit-log, /admin/customers/:id/audit-log.

2026-04-22 — v1.3

• Manufacturing module: production orders, BOM, material-plan endpoints, finished-goods stock updates on completion.
• Pick list workflow with per-line picking, package definition, ship from pick list.
• Returns RMA lifecycle endpoints.

2026-03-15 — v1.2

• Marketplace mode: vendors, Stripe Connect onboarding, per-vendor earnings, payouts, statements.
• Affiliate program: tracking links, earnings, payouts, creative content approval.

2026-02-10 — v1.1

• Multi-warehouse inventory with sub-locations.
• Atomic stock reservation in checkout.
• Tax classes + shipping-country VAT.

2026-01-12 — v1.0

• Initial release — orders, products, customers, cart, checkout, Stripe payments, Sendcloud labels, base invoicing.

SDKs

Official SDKs are planned for v2. Until then, the API is plain REST + JSON — any HTTP client works.

Generated OpenAPI spec

The OpenAPI 3.1 spec is available at https://api.sellforge.ai/openapi.json. Use it to generate clients in your language of choice with openapi-generator or Stainless.

Support

Got a question that isn't answered here?

• Email hello@sellforge.ai — typical response within 12h on Studio/Atelier, 1h on Forge tier
• Status page: status.sellforge.ai
• Changelog RSS: sellforge.ai/changelog.rss
• Discord community (Atelier+): discord.gg/sellforge