Documentation

Everything you need to connect a shop, understand the sync pipeline and build on top of the DKH API.

Quickstart

Create an account at /register.
Open Dashboard → Shops and choose Connect shop.
Pick your marketplace and approve the permissions on its authorization screen.
Wait for the first sync to finish — listings first, then orders.
Open Orders; your queue is live.

Connect an Etsy shop

DKH uses the Etsy Open API v3 with OAuth 2.0 and PKCE. The flow is:

You click Connect Etsy. DKH generates a PKCE verifier and redirects you to https://www.etsy.com/oauth/connect.
Etsy shows you the requested scopes: shops_r listings_r transactions_r transactions_w.
After you approve, Etsy redirects back to /api/integrations/etsy/callback with an authorization code.
DKH exchanges the code for an access token and a refresh token at https://api.etsy.com/v3/public/oauth/token, then stores them encrypted.
The shop record is created and the first sync starts: /shops/{shop_id}/listings/active then /shops/{shop_id}/receipts.

Self-hosting? Set ETSY_CLIENT_ID, ETSY_CLIENT_SECRET and ETSY_REDIRECT_URI in your environment. The redirect URI must match the callback registered in your Etsy app exactly.

ETSY_CLIENT_ID="your-keystring"
ETSY_CLIENT_SECRET="your-shared-secret"
ETSY_REDIRECT_URI="https://yourdomain.com/api/integrations/etsy/callback"
ETSY_SCOPES="shops_r listings_r transactions_r transactions_w"

Without credentials the platform runs in demo mode: connecting a shop creates a simulated channel with realistic data so the workflow can be reviewed end-to-end.

How syncing works

Each shop is synced on a schedule (15 minutes by default) and on demand.
Records are matched by the marketplace's own id, so re-syncing never duplicates.
Every run creates a sync job with counts, duration and any error.
Access tokens are refreshed automatically five minutes before expiry.
Rate-limit responses trigger exponential backoff; the run resumes where it stopped.

Automations

An automation is a trigger, a set of conditions and a list of actions.

{
  "name": "Flag high-value orders",
  "trigger": "ORDER_CREATED",
  "conditions": [{ "field": "total", "op": "gt", "value": 150 }],
  "actions": [
    { "type": "SET_PRIORITY", "value": "HIGH" },
    { "type": "ADD_TAG", "value": "vip" }
  ]
}

Supported triggers: ORDER_CREATED, ORDER_PAID, ORDER_SHIPPED, SYNC_COMPLETED, SCHEDULE. Supported actions: SET_STATUS, SET_PRIORITY, ADD_TAG, NOTIFY, PUSH_TRACKING and WEBHOOK.

REST API

Authenticate with an API key from Dashboard → API keys. Send it as a bearer token.

curl https://dkh-io.vercel.app/api/v1/orders?status=NEW&limit=25 \
  -H "Authorization: Bearer dkh_live_xxxxxxxxxxxx"

Method	Endpoint	Description
GET	/api/v1/orders	List orders, filterable by status, shop and date
GET	/api/v1/orders/{id}	Retrieve a single order with items and shipments
PATCH	/api/v1/orders/{id}	Update status, priority, tags or notes
POST	/api/v1/orders/{id}/shipments	Create a shipment and push tracking
GET	/api/v1/shops	List connected shops and their sync state
POST	/api/v1/shops/{id}/sync	Trigger an immediate sync
GET	/api/v1/products	List synced listings

Webhooks — not available yet

Outbound webhooks are not implemented. You can register an endpoint in Dashboard → API keys and it will be stored against your account, but DKH does not deliver events to it today. Poll GET /api/v1/orders instead until this ships.

When it does ship, deliveries will be signed with HMAC-SHA256 in an X-DKH-Signature header and cover order.created, order.updated, order.shipped and shop.sync_failed. We will announce it here and by email before enabling it.

Errors & rate limits

400 — malformed request
401 — missing or invalid API key
403 — key lacks the required scope
404 — resource not found or not yours
429 — rate limited; check the Retry-After header
5xx — our problem; safe to retry with backoff

API keys are limited to 120 requests per minute per account.