Developer documentation

Getting started

The API lives under https://sellhidden.com/api/v1. Public endpoints need no key and are safe to call from a browser: they serve products, categories, visible reviews and recent sales for one store. Authenticated endpoints need a personal access key and expose your orders, customers, tickets, coupons and analytics; call them from your server only.

Every response is JSON. Times are ISO 8601 in UTC. Money is USD with two decimals unless a field says otherwise. Ids are opaque strings; do not parse them.

GET https://sellhidden.com/api/v1
# → lists every endpoint with its full URL

Authentication

Create a key under Developers, API keys in your dashboard. Keys start with sk_live_, are scoped to the store that issued them, and are shown once: we keep only a SHA-256 hash and the first characters for display. Up to 10 keys can be active per store; revoking one keeps it listed for the audit trail.

curl https://sellhidden.com/api/v1/orders?status=paid&limit=25 \
  -H "Authorization: Bearer sk_live_…"

A missing or invalid key returns 401 with code: "unauthorized"; a revoked key returns 401 with code: "key_revoked"; a suspended store returns 403. Rotate a key immediately if it leaks: create a new one, switch your integration, then revoke the old one.

Responses and errors

Every body carries an ok boolean. Successful responses put their data next to it; failures carry a human-readable error and a stable code you can branch on.

{ "ok": true, "products": [ … ], "nextCursor": "Y2xxazF…", "hasMore": true }

{ "ok": false, "error": "Invalid API key.", "code": "unauthorized" }

Rate limits

Public endpoints allow 120 requests per minute per IP address and are cached for 60 seconds (cache-control: public, s-maxage=60), so a busy page rarely hits the origin. Authenticated endpoints allow 120 requests per minute per key. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 also includes Retry-After in seconds.

Pagination

List endpoints are cursor-based and return newest first. Pass limit (default and maximum vary per endpoint) and, for the next page, the nextCursor from the previous response. Cursors are opaque; do not build them yourself.

# First page
GET https://sellhidden.com/api/v1/orders?limit=50

# Next page: pass the cursor from the previous response
GET https://sellhidden.com/api/v1/orders?limit=50&cursor=Y2xxazF…

# Stop when "hasMore" is false (nextCursor is then null)

Webhooks

Add endpoints under Developers, Webhooks. Each endpoint has a label, a list of subscribed events, its own signing secret (shown once; rotate it any time) and a delivery log you can filter and resend from. Plans allow 1 endpoint on Free, 5 on Starter and unlimited on Pro and Enterprise; logs are kept 7, 14, 30 and 90 days respectively. Endpoints must be public https URLs; private and local addresses are rejected.

Events

Headers and payload

Deliveries are JSON POSTs. X-Hidden-Event names the event, X-Hidden-Delivery is a unique id per delivery attempt, X-Hidden-Timestamp is unix seconds and X-Hidden-Signature carries the HMAC. Order events share one data shape:

POST https://example.com/hooks/hidden
Content-Type: application/json
User-Agent: Hidden-Webhooks/1.0 (+https://sellhidden.com)
X-Hidden-Event: order.paid
X-Hidden-Timestamp: 1790000000
X-Hidden-Signature: sha256=3f8a…c21e
X-Hidden-Delivery: whd_01j9…

{
  "id": "evt_9f2c…",
  "event": "order.paid",
  "createdAt": "2026-09-26T10:01:12.000Z",
  "data": {
    "orderId": "clx…",
    "storeId": "clx…",
    "status": "paid",
    "buyerEmail": "buyer@example.com",
    "grossUsd": 29,
    "discountUsd": 0,
    "buyerTotalUsd": 29,
    "sellerNetUsd": 27.90,
    "platformFeeUsd": 1.10,
    "couponCode": null,
    "paymentMethod": "crypto",
    "paidAt": "2026-09-26T10:01:12.000Z",
    "deliveredAt": null,
    "createdAt": "2026-09-26T09:58:40.000Z",
    "items": [
      { "itemId": "clx…", "productId": "clx…", "title": "Lifetime license", "variantId": "clx…", "quantity": 1, "unitPriceUsd": 29, "deliveryStatus": "pending" }
    ]
  }
}

Respond with any 2xx status within 15 seconds. Anything else counts as a failure. The body you return is ignored.

Verifying signatures

Every delivery is signed with HMAC-SHA256. The signed string is the timestamp header, a dot, and the raw request body. Compute the digest with the endpoint secret, compare it in constant time with the header value (after the sha256= prefix), and reject anything older than a few minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

// Use the raw request body exactly as received (do not JSON.parse first).
export function verifyHiddenSignature(rawBody: string, headers: Headers, secret: string) {
  const header = headers.get("x-hidden-signature") ?? "";      // "sha256=<hex>"
  const timestamp = headers.get("x-hidden-timestamp") ?? "";   // unix seconds

  // Reject stale deliveries (replay protection), 5 minute tolerance.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const given = header.replace(/^sha256=/, "");
  if (given.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(given, "hex"), Buffer.from(expected, "hex"));
}

// Next.js route handler
export async function POST(req: Request) {
  const raw = await req.text();
  if (!verifyHiddenSignature(raw, req.headers, process.env.HIDDEN_WEBHOOK_SECRET!)) {
    return new Response("invalid signature", { status: 401 });
  }
  const event = JSON.parse(raw);
  // De-duplicate on the X-Hidden-Delivery header before acting.
  // ...handle event.data
  return new Response("ok");
}

import hmac, hashlib, time

def verify_hidden_signature(raw_body: bytes, headers: dict, secret: str) -> bool:
    given = headers.get("x-hidden-signature", "").removeprefix("sha256=")
    ts = headers.get("x-hidden-timestamp", "0")
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(given, expected)

Retries and idempotency

A delivery that times out or gets a 5xx, 408 or 429 response is retried up to six times, roughly 1, 5, 30, 120, 360 and 1440 minutes after the first attempt. Other 4xx responses are treated as permanent and not retried. Every retry carries the same X-Hidden-Delivery id with a fresh timestamp and signature, so store that id and ignore duplicates. After 6 consecutive failures the endpoint is switched off; fix your receiver and switch it back on in the dashboard.

The dashboard log shows every attempt with its status code and when the next retry is due. Use Send test event to receive a signed webhook.test delivery, and Resend on any failed row to replay its exact payload.

Dynamic delivery

Set a product's delivery type to dynamic and paste your endpoint URL. On every paid order Hidden POSTs the signed order payload (same format as a webhook) and delivers the deliveredData string from your JSON response. Use it to provision accounts, generate keys on the fly, or call your own licensing server.

// Your endpoint receives the same signed payload as a webhook.
// Respond within 10 seconds with what the buyer should receive:
HTTP/1.1 200 OK
Content-Type: application/json

{
  "deliveredData": "Your licence: HDN-4K2P-88QL-9XQ1\nActivate at https://example.com/activate",
  "note": "Shown to the buyer under the item (optional)"
}

// Anything other than 2xx (or a timeout) marks the item "failed" with your response
// body as the error. You can redeliver from the order page in the dashboard.

Embed and live price

Give any element data-hidden-store and data-hidden-product, include embed.js once, and clicking opens a checkout modal with your live product page. The buyer never leaves the host page; the modal closes with its X, Escape, a click outside, or from checkout once the order is placed.

<button data-hidden-store="my-store" data-hidden-product="lifetime-license">Buy now</button>
<script src="https://sellhidden.com/embed.js" async></script>

A price span keeps itself current from the public API (cached 60 seconds). Optional attributes: data-hidden-price-prefix, data-hidden-currency-symbol and data-hidden-format="raw". Once loaded the span gets data-hidden-in-stock="true|false".

<span data-hidden-price="my-store/lifetime-license" data-hidden-price-prefix="from "></span>

Open and close the modal from your own code, or rebind after rendering new elements in a single-page app:

window.HiddenEmbed.open("my-store", "lifetime-license"); // open the checkout modal
window.HiddenEmbed.close();                                // close it
window.HiddenEmbed.scan();                                 // bind elements added after load

Prefer your own markup? Fetch the product and render the price yourself:

const res = await fetch("https://sellhidden.com/api/v1/public/products/my-store/lifetime-license");
const { ok, product } = await res.json();
if (ok) priceEl.textContent = `$${product.displayPriceUsd.toFixed(2)}`;

The script sets no cookies, reads nothing on the host page and takes the checkout host from its own src, so a copied snippet cannot be redirected. Messages from the modal are accepted only from that origin. The v1 snippet (<script data-store data-product>) keeps working and now opens the modal too.

Delivery types

Every product has a delivery type that decides what the buyer receives when an order is paid. Delivery runs automatically once the network confirms; nothing is revealed for pending, expired or cancelled orders.

• Files

  deliveryType: "file"

  Signed download link.

• Text and credentials

  deliveryType: "text"

  Revealed after payment.

• License and serial keys

  deliveryType: "keys"

  One unique key per order.

• Private links

  deliveryType: "link"

  URL unlocked on payment.

• Discord roles

  deliveryType: "discord"

  Granted by the bot on payment.

• Dynamic delivery

  deliveryType: "dynamic"

  Your webhook decides.

Buyer accounts and payments

Buyers never create a password. On any storefront they can sign in with their email and a 6-digit one-time code (valid 10 minutes), which unlocks an account page with their orders, reviews (editable for 24 hours), support tickets and a store balance. The session is a per-store cookie that lasts 30 days.

Orders exposed through the API carry kind (product or topup), payment.method (crypto, balance, manual or free) and, for manual rails, the claim and verification timestamps, so integrations can tell a settled crypto order from one still awaiting the seller.

Testing

Create a $0 product to walk through checkout, the order page and delivery without a payment. To exercise webhooks, press Send test event on an endpoint, or use a low-priced product and pay a small USDT amount; the fee is only charged on the confirmed amount. Any order can be redelivered from its order page, which sends its events again with the same delivery id.