Skip to content
Free UPS Ground on orders $100+
SmallBatchDANK
API version 2026-10-20

Partner API reference

Everything an approved partner needs to put our small-batch catalog on their site and ship to their customers: REST over HTTPS, JSON in and out, scoped keys, idempotent writes and signed webhooks.

Overview

Base URL https://smallbatchdank.com. Sandbox and live keys use the same URL; sandbox keys only ever see fixture data. Every response carries an x-request-id — quote it when you contact us.

CredentialLooks likeUse it
Secret keysbd_sk_live_… / sbd_sk_test_…Server-side only, as a Bearer token
OAuth clientsbd_cl_… + sbd_cs_…Exchange for a 1-hour sbd_at_… token
Publishable keysbd_pk_live_…Embeds on your allowed domains; read-only
Webhook secretsbd_whsec_…Verify SBD-Signature on deliveries

Authentication

Send Authorization: Bearer <secret key or access token>. Keys are shown once when created and stored only as a salted hash — if you lose one, rotate it: the old key keeps working for 24 hours so you can deploy without downtime. Live access needs our approval; sandbox is instant. Optionally lock an integration to server IPs.

OAuth 2.0 client credentials
curl -s -X POST https://smallbatchdank.com/v1/oauth/token \
  -d grant_type=client_credentials -d client_id=$SBD_CLIENT_ID \
  -d client_secret=$SBD_CLIENT_SECRET -d scope="products:read inventory:read"
# → {"access_token":"sbd_at_…","token_type":"Bearer","expires_in":3600,"scope":"products:read inventory:read"}

Publishable keys go in the X-SBD-Publishable-Key header (the embed script does this) and work only from origins on your allowlist, only on read endpoints, and never return your price book.

Scopes

An integration is granted a set of scopes; each key or token carries a subset. Publishable keys are limited to products:read, inventory:read, media:read, coa:read.

  • products:readProducts and variants
  • inventory:readAvailable-to-sell (bands or capped quantities)
  • pricing:readYour price book
  • media:readProduct images
  • coa:readLab results (COAs)
  • orders:writeCancel orders before fulfillment
  • orders:readYour orders
  • fulfillment:readPacking and shipment status
  • tracking:readTracking numbers and events
  • webhooks:writeManage webhook endpoints
  • white_label:readYour white-label projects
  • dropship:writeCreate dropship orders and stock holds

Conventions

  • Idempotency. Every POST accepts Idempotency-Key (up to 80 characters). A retry with the same key and body replays the first response with idempotent-replayed: true; the same key with a different body is idempotency_conflict. Keys are kept for 24 hours.
  • Pagination. Lists return { object: "list", data, has_more, next_cursor }. Pass cursor=next_cursor and limit (1–200).
  • Caching. GET responses carry an ETag; send it back as If-None-Match to get a 304 without a body.
  • Money is integer cents in USD. Stock is a band (OUT, LIMITED, AVAILABLE, DEEP) unless your integration is enabled for capped quantities.
  • Dropship ships to US addresses only and follows the same shipping rules as our own store. Orders are paid from your partner balance or net terms — never a card. Packing slips are blind: your brand, your SKUs, no mention of us.

Endpoints

Auth

POST/v1/oauth/token

Exchange client credentials for a short-lived access token

client credentialsIdempotency-Key

Body (JSON)

FieldTypeNotes
grant_type*string
client_id*string
client_secret*string
scopestring

Catalog

GET/v1/products

List the products and variants available to you

products:readpublishable key OK

Query

FieldTypeNotes
limitintegerdefault 50 · max 200
cursorstring
categorystring
skustring

GET/v1/products/:id

Get one variant (by id or SKU)

products:readpublishable key OK

GET/v1/pricing

Your price book: MSRP, minimums and quantity breaks

pricing:read

Query

FieldTypeNotes
limitintegerdefault 50 · max 200
cursorstring

GET/v1/coas/:batch

Lab results for a batch you can sell

coa:readpublishable key OK

Inventory

GET/v1/inventory

Available-to-sell bands (or capped quantities) for every visible variant

inventory:readpublishable key OK

Query

FieldTypeNotes
limitintegerdefault 50 · max 200
cursorstring
skustring

Reservations

POST/v1/reservations

Hold stock for a checkout (all lines or none)

dropship:writeIdempotency-Key

Body (JSON)

FieldTypeNotes
partner_refstring
ttl_minutesintegermax 2880
lines*array<object>

GET/v1/reservations/:id

Get a stock hold

dropship:write

DELETE/v1/reservations/:id

Release a stock hold

dropship:write

Orders

POST/v1/dropship/orders

Create a dropship order shipped to your customer (blind packing)

dropship:writeIdempotency-Key

Body (JSON)

FieldTypeNotes
partner_order_id*string
reservation_idstring
shipping_serviceGROUND | SECOND_DAY | OVERNIGHTdefault "GROUND"
ship_to*object
customer_emailstring
lines*array<object>

GET/v1/orders/:id

Get one of your orders (DS number, id, or your partner_order_id)

orders:read

GET/v1/orders/:id/tracking

Tracking for one of your orders

tracking:read

POST/v1/orders/:id/cancel

Cancel before a label is bought; refunds your partner account

orders:writeIdempotency-Key

Body (JSON)

FieldTypeNotes
reasonstring

Webhooks

GET/v1/webhooks

List your webhook endpoints

webhooks:write

POST/v1/webhooks

Add a webhook endpoint (the signing secret is returned once)

webhooks:writeIdempotency-Key

Body (JSON)

FieldTypeNotes
url*string
events*array<string>
descriptionstring

DELETE/v1/webhooks/:id

Delete a webhook endpoint

webhooks:write

White label

GET/v1/white-label/projects

Your white-label projects and their status

white_label:read

Sandbox

POST/v1/sandbox/orders/:id/advance

Sandbox only: move a test order to its next status and fire its webhook

dropship:writeIdempotency-Keysandbox only

Webhooks

Add HTTPS endpoints in the portal or with POST /v1/webhooks. Deliveries are POSTs with a JSON event; answer 2xx within 10 seconds. Failures retry with backoff (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h) and then dead-letter; you can redeliver any event from the portal. Redirects aren’t followed and private addresses are refused.

  • product.created
  • product.updated
  • inventory.updated
  • price.updated
  • batch.created
  • coa.updated
  • reservation.expired
  • order.created
  • order.paid
  • order.packed
  • order.shipped
  • order.delivered
  • order.exception
Event
{
  "id": "evt_8sKq2…",
  "object": "event",
  "type": "order.shipped",
  "api_version": "2026-10-20",
  "created": 1792500000,
  "livemode": true,
  "test": false,
  "data": { "object": { "object": "dropship_order", "number": "DS-5012", "partner_order_id": "1001", "status": "SHIPPED", "tracking": { "carrier": "UPS", "number": "1Z…" } } }
}

Verifying SBD-Signature

SBD-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
  1. Recompute the HMAC over the exact raw body bytes and compare in constant time.
  2. Reject when |now − t| is more than 300 seconds.
  3. Store processed event ids and ignore repeats — retries can deliver the same event twice.
  4. During a secret rotation two v1 values are sent for 24 hours; accept either.

Errors

{ "error": { "code": "insufficient_stock", "message": "…", "details": { … }, "request_id": "req_…" } }
CodeHTTPMeaning
invalid_request422A field is missing or malformed — details.field names it.
unauthorized401Missing, unknown, expired or revoked credential.
insufficient_scope403The key or token lacks the scope this endpoint needs.
client_not_active403The integration is waiting for approval, suspended or revoked.
origin_not_allowed403A publishable key was used from a domain not on your allowlist.
ip_not_allowed403The request came from an IP outside your allowlist.
not_found404Nothing with that id is visible to your integration.
idempotency_conflict409The Idempotency-Key was reused with a different body.
idempotency_in_progress409The first request with this key is still running — retry shortly.
insufficient_stock409Not enough available for at least one line; details lists them. Nothing was held.
conflict409The object is in a state that doesn’t allow this (e.g. already shipped).
not_dropship_eligible422The SKU isn’t available to your integration for dropship.
not_in_price_book422The SKU has no price in your price book.
below_minimum422The quantity is below the item’s minimum.
address_invalid422The ship-to address can’t be shipped to (US only for dropship).
compliance_blocked422Shipping rules for the destination don’t allow this item.
insufficient_balance402Your prepaid partner balance doesn’t cover the order.
credit_limit_exceeded402The order would exceed your credit limit or you have an overdue invoice.
rate_limited429Slow down — see Retry-After.
internal_error500Our side. Safe to retry with the same Idempotency-Key.

Rate limits

A token bucket per integration. Every response has RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 adds Retry-After.

  • standard120 burst10 requests/second sustained
  • elevated300 burst25 requests/second sustained
  • high600 burst50 requests/second sustained

Sandbox

Sandbox integrations are self-serve from the portal and return fixtures — no stock, orders or money move. Test orders can be stepped through their lifecycle with POST /v1/sandbox/orders/:id/advance, which fires the matching webhook each time.

  • SANDBOX-FLWR-35120 available
  • SANDBOX-FLWR-288 available
  • SANDBOX-ROSN-35out of stock
  • SANDBOX-PRE-540 available

Embeds

One script, no build step. Widgets render inside a Shadow DOM so styles never collide, need no inline script (CSP-friendly) and only ever use your publishable key.

HTML
<script src="https://smallbatchdank.com/embed/v1/sbd.js" data-key="sbd_pk_live_…" defer></script>
<div data-sbd-widget="product-grid" data-category="FLOWER" data-limit="8" data-link="https://yourshop.com/p/{sku}"></div>
<span data-sbd-widget="inventory-badge" data-sku="MY-SKU-35"></span>
<button data-sbd-widget="product-modal" data-sku="MY-SKU-35">Details</button>
<div data-sbd-widget="coa" data-batch="B-2026-11"></div>
<a data-sbd-widget="quick-order" data-sku="MY-SKU-35">Reorder wholesale</a>

Examples

curl
# List products with your price book and stock bands
curl -s "https://smallbatchdank.com/v1/products?limit=50" \
  -H "Authorization: Bearer $SBD_SECRET_KEY"

# Hold stock for a checkout (all lines or none), then convert the hold
curl -s -X POST https://smallbatchdank.com/v1/reservations \
  -H "Authorization: Bearer $SBD_SECRET_KEY" -H "Idempotency-Key: cart-8842" \
  -H "Content-Type: application/json" \
  -d '{"partner_ref":"cart-8842","ttl_minutes":30,"lines":[{"sku":"MY-SKU-35","qty":2}]}'

curl -s -X POST https://smallbatchdank.com/v1/dropship/orders \
  -H "Authorization: Bearer $SBD_SECRET_KEY" -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"partner_order_id":"1001","reservation_id":"<id>","shipping_service":"GROUND",
       "ship_to":{"name":"Alex Rivera","line1":"100 Main St","city":"Austin","region":"TX","postal":"78701","country":"US"},
       "lines":[{"sku":"MY-SKU-35","qty":2,"retail_price_cents":4800}]}'
JavaScript / TypeScript
import { SmallBatchDank, verifyWebhook } from '@sbd/partner-sdk';

const sbd = new SmallBatchDank({ apiKey: process.env.SBD_SECRET_KEY });
const { data } = await sbd.products.list({ limit: 100 });
const order = await sbd.dropship.create(
  { partner_order_id: '1001', ship_to: { name: 'Alex Rivera', line1: '100 Main St', city: 'Austin', region: 'TX', postal: '78701', country: 'US' }, lines: [{ sku: 'MY-SKU-35', qty: 2 }] },
  { idempotencyKey: 'order-1001' },
);

// Express — verify against the RAW body
app.post('/webhooks/sbd', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = verifyWebhook(req.body, req.header('SBD-Signature'), process.env.SBD_WEBHOOK_SECRET, { seen: (id) => processed.has(id) });
    processed.add(event.id);
    res.sendStatus(200);
  } catch {
    res.sendStatus(400);
  }
});
Python
import hashlib, hmac, json, os, time, requests

r = requests.get("https://smallbatchdank.com/v1/inventory",
                 headers={"Authorization": f"Bearer {os.environ['SBD_SECRET_KEY']}"})
for item in r.json()["data"]:
    print(item["sku"], item["band"])

def verify(raw: bytes, header: str, secret: str, tolerance: int = 300) -> dict:
    parts = [p.split("=", 1) for p in header.split(",") if "=" in p]
    t = int(dict(parts)["t"])
    if abs(time.time() - t) > tolerance:
        raise ValueError("stale signature")
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    if not any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts):
        raise ValueError("bad signature")
    return json.loads(raw)  # then drop repeats of event["id"]

Shopify and WooCommerce connectors are planned; the API, webhooks and embeds cover custom storefronts today.

Changelog

  • 2026-10-20 — First public version: catalog, inventory bands, pricing, COAs, stock holds, dropship orders, tracking, webhooks, white-label projects, OAuth client credentials and embeds.