POST/v1/oauth/token
Exchange client credentials for a short-lived access token
client credentialsIdempotency-Key
Body (JSON)
| Field | Type | Notes |
|---|---|---|
| grant_type* | string | |
| client_id* | string | |
| client_secret* | string | |
| scope | string |
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.
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.
| Credential | Looks like | Use it |
|---|---|---|
| Secret key | sbd_sk_live_… / sbd_sk_test_… | Server-side only, as a Bearer token |
| OAuth client | sbd_cl_… + sbd_cs_… | Exchange for a 1-hour sbd_at_… token |
| Publishable key | sbd_pk_live_… | Embeds on your allowed domains; read-only |
| Webhook secret | sbd_whsec_… | Verify SBD-Signature on deliveries |
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.
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.
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 variantsinventory:readAvailable-to-sell (bands or capped quantities)pricing:readYour price bookmedia:readProduct imagescoa:readLab results (COAs)orders:writeCancel orders before fulfillmentorders:readYour ordersfulfillment:readPacking and shipment statustracking:readTracking numbers and eventswebhooks:writeManage webhook endpointswhite_label:readYour white-label projectsdropship:writeCreate dropship orders and stock holdsIdempotency-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.{ object: "list", data, has_more, next_cursor }. Pass cursor=next_cursor and limit (1–200).ETag; send it back as If-None-Match to get a 304 without a body.POST/v1/oauth/token
Exchange client credentials for a short-lived access token
client credentialsIdempotency-Key
Body (JSON)
| Field | Type | Notes |
|---|---|---|
| grant_type* | string | |
| client_id* | string | |
| client_secret* | string | |
| scope | string |
GET/v1/products
List the products and variants available to you
products:readpublishable key OK
Query
| Field | Type | Notes |
|---|---|---|
| limit | integer | default 50 · max 200 |
| cursor | string | |
| category | string | |
| sku | string |
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
| Field | Type | Notes |
|---|---|---|
| limit | integer | default 50 · max 200 |
| cursor | string |
GET/v1/coas/:batch
Lab results for a batch you can sell
coa:readpublishable key OK
GET/v1/inventory
Available-to-sell bands (or capped quantities) for every visible variant
inventory:readpublishable key OK
Query
| Field | Type | Notes |
|---|---|---|
| limit | integer | default 50 · max 200 |
| cursor | string | |
| sku | string |
POST/v1/reservations
Hold stock for a checkout (all lines or none)
dropship:writeIdempotency-Key
Body (JSON)
| Field | Type | Notes |
|---|---|---|
| partner_ref | string | |
| ttl_minutes | integer | max 2880 |
| lines* | array<object> |
GET/v1/reservations/:id
Get a stock hold
dropship:write
DELETE/v1/reservations/:id
Release a stock hold
dropship:write
POST/v1/dropship/orders
Create a dropship order shipped to your customer (blind packing)
dropship:writeIdempotency-Key
Body (JSON)
| Field | Type | Notes |
|---|---|---|
| partner_order_id* | string | |
| reservation_id | string | |
| shipping_service | GROUND | SECOND_DAY | OVERNIGHT | default "GROUND" |
| ship_to* | object | |
| customer_email | string | |
| 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)
| Field | Type | Notes |
|---|---|---|
| reason | string |
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)
| Field | Type | Notes |
|---|---|---|
| url* | string | |
| events* | array<string> | |
| description | string |
DELETE/v1/webhooks/:id
Delete a webhook endpoint
webhooks:write
GET/v1/white-label/projects
Your white-label projects and their status
white_label:read
POST/v1/sandbox/orders/:id/advance
Sandbox only: move a test order to its next status and fire its webhook
dropship:writeIdempotency-Keysandbox only
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.
{
"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>")>{ "error": { "code": "insufficient_stock", "message": "…", "details": { … }, "request_id": "req_…" } }| Code | HTTP | Meaning |
|---|---|---|
| invalid_request | 422 | A field is missing or malformed — details.field names it. |
| unauthorized | 401 | Missing, unknown, expired or revoked credential. |
| insufficient_scope | 403 | The key or token lacks the scope this endpoint needs. |
| client_not_active | 403 | The integration is waiting for approval, suspended or revoked. |
| origin_not_allowed | 403 | A publishable key was used from a domain not on your allowlist. |
| ip_not_allowed | 403 | The request came from an IP outside your allowlist. |
| not_found | 404 | Nothing with that id is visible to your integration. |
| idempotency_conflict | 409 | The Idempotency-Key was reused with a different body. |
| idempotency_in_progress | 409 | The first request with this key is still running — retry shortly. |
| insufficient_stock | 409 | Not enough available for at least one line; details lists them. Nothing was held. |
| conflict | 409 | The object is in a state that doesn’t allow this (e.g. already shipped). |
| not_dropship_eligible | 422 | The SKU isn’t available to your integration for dropship. |
| not_in_price_book | 422 | The SKU has no price in your price book. |
| below_minimum | 422 | The quantity is below the item’s minimum. |
| address_invalid | 422 | The ship-to address can’t be shipped to (US only for dropship). |
| compliance_blocked | 422 | Shipping rules for the destination don’t allow this item. |
| insufficient_balance | 402 | Your prepaid partner balance doesn’t cover the order. |
| credit_limit_exceeded | 402 | The order would exceed your credit limit or you have an overdue invoice. |
| rate_limited | 429 | Slow down — see Retry-After. |
| internal_error | 500 | Our side. Safe to retry with the same Idempotency-Key. |
A token bucket per integration. Every response has RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 adds Retry-After.
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 availableSANDBOX-FLWR-288 availableSANDBOX-ROSN-35out of stockSANDBOX-PRE-540 availableOne 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.
<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># 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}]}'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);
}
});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.

SmallBatchDANK sells hemp-derived products for adults 21+ only. Availability depends on your location.
By entering you agree to our Terms and Privacy Policy.