API Reference

BestWebby REST API — authenticate, manage products, orders, inventory, and webhooks. Base URL: https://api.bestwebby.com/v1

Overview

BestWebby exposes a RESTful API for integrating with your own tools, building custom workflows, and extending the platform.

Base URL: https://api.bestwebby.com/v1

Authentication: Bearer token (API key from Settings → Developer → API Keys)

Rate limits: 1,000 requests/minute on Growth; 5,000/minute on Scale; 10,000/minute on Enterprise

Format: All requests and responses are JSON.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer bw_live_xxxxxxxxxxxxxxxxxxxx

API keys are scoped to your merchant account. Keep them secret — treat them like passwords. Rotate via Settings → Developer → API Keys if compromised.

Products

List products

GET /v1/products

Query parameters:

page (integer, default: 1)
per_page (integer, default: 20, max: 100)
status (string: active | draft | recalled)
category_id (string)

Response:

{
  "data": [
    {
      "id": "prod_xxxx",
      "name": "Classic Wool Sweater",
      "status": "active",
      "price_cents": 4999,
      "stock": 142,
      "sku": "WS-001-BLU-M",
      "category_id": "cat_xxxx",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 847 }
}

Create product

POST /v1/products

Body:

{
  "name": "Classic Wool Sweater",
  "description": "100% merino wool...",
  "price_cents": 4999,
  "stock": 50,
  "sku": "WS-001-BLU-M",
  "status": "draft"
}

Update product

PATCH /v1/products/:id

Delete product

DELETE /v1/products/:id

Orders

List orders

GET /v1/orders

Query parameters:

status (string: pending | processing | shipped | delivered | cancelled)
channel (string: storefront | amazon | etsy | pos | ...)
from (ISO 8601 date)
to (ISO 8601 date)

Get order

GET /v1/orders/:id

Update order status

PATCH /v1/orders/:id/status

Body:

{ "status": "shipped", "tracking_number": "1Z999AA10123456784" }

Inventory

Get inventory level

GET /v1/inventory/:product_id

Adjust inventory

POST /v1/inventory/:product_id/adjust

Body:

{
  "delta": -5,
  "reason": "damaged_goods",
  "note": "Water damage on receiving, batch 2026-05"
}

Webhooks

BestWebby sends webhook events for key platform actions. Register endpoints in Settings → Developer → Webhooks.

Available events:

order.created
order.status_changed
inventory.low_stock (fires when stock falls below reorder point)
recall.created
payment.received
subscription.churned

Webhook payload:

{
  "event": "order.created",
  "created_at": "2026-05-17T14:32:00Z",
  "data": { "order_id": "ord_xxxx", ... }
}

Verify webhook authenticity using the X-BestWebby-Signature header (HMAC-SHA256 of the raw body signed with your webhook secret).

Error codes

Code	Meaning
400	Bad request — check request body
401	Authentication failed — check API key
403	Insufficient permissions for this action
404	Resource not found
422	Validation error — see `errors` array in response
429	Rate limit exceeded
500	Server error — contact support if persistent

SDK

Official SDKs (planned):

Node.js: npm install @bestwebby/sdk
Python: pip install bestwebby
PHP: composer require bestwebby/sdk

SDKs are in development and will be published alongside the public API launch. Until then, the REST API is the primary integration surface.

Questions

API questions: [email protected] or the #api-support channel in our developer Discord (invite at /docs/discord).