Add live price drops to your store.

The embed

Load the script once per page, then place a <freefall-market> element wherever drops should appear. It's a standard web component that renders in its own Shadow DOM, so your CSS can't break it and it doesn't add globals to your page.

<script src="https://freefallexchange.com/embed/v1.js" async></script>
<freefall-market store="pk_live_…" limit="6" layout="grid" theme="auto"></freefall-market>

Prices stream live over a WebSocket. The page's origin must be in the store's Allowed origins (exact match, https://, no wildcards; http://localhost is accepted for testing). Embedding needs Trader or higher.

Browser events

When a shopper completes a purchase in the Freefall window, the element fires freefall:purchased. It bubbles to document. Use it to update your page (say thanks, refresh a cart). Fulfil orders from the webhook, not from this event.

document.addEventListener('freefall:purchased', (e) => {
  const { orderNumber, lockId, dropId, externalProductId, unitPrice, quantity, total, currency } = e.detail;
  console.log(`Order ${orderNumber}: ${quantity} × ${unitPrice} ${currency}`);
});

Keys

• Publishable key (pk_live_…): identifies your store in embeds and the market API. Safe in page source.
• Secret key (sk_live_…): for your server only. Shown once when created; Freefall keeps only a hash. Rotate it on the Embed & API keys page; the old key stops working immediately.
• Webhook signing secret (whsec_…): verifies webhook requests. Rotate it on the same page.

Market API

GET /api/v1/market/{publishableKey}: the store and its visible drops right now (what the embed loads first). Public, read-only, and checked against Allowed origins when called from a browser.

{
  "serverTimeMs": 1760700000000,
  "store": { "id": "…", "name": "Sunny Sneakers", "slug": "sunny-sneakers", "tagline": "Fresh kicks, falling live.",
             "accentColor": "#ff3d71", "currency": "usd", "acceptsCheckout": true, … },
  "drops": [{
    "id": "…", "title": "Volt Runner 2", "subtitle": "Carbon plate racing flats", "imageUrl": null,
    "retailPrice": 220, "startPrice": 210, "price": 198.12, "status": "Live",
    "quantity": 40, "sold": 0, "available": 40, "maxPerOrder": 1,
    "tickSeconds": 2, "nextTickMs": 1760700001000, "history": [210, 209.4, …]
  }]
}

status is Live, Scheduled, Paused or SoldOut. The floor price is never sent. Errors: 404 unknown or unpublished store, 403 website not in Allowed origins, 429 too many requests.

Server API

Read-only lookups for your backend, authenticated with your secret key: Authorization: Bearer sk_live_…. Requests that come from a browser (with an Origin header) are refused, so a secret key that ends up in front-end code fails straight away.

Look up an order

curl https://freefallexchange.com/api/v1/host/orders/{orderNumber} \
  -H "Authorization: Bearer sk_live_…"

Returns the same order object as the webhook.

Look up a lock

curl https://freefallexchange.com/api/v1/host/locks/{lockId} \
  -H "Authorization: Bearer sk_live_…"

{
  "lockId": "…", "status": "Completed", "open": false,
  "dropId": "…", "externalProductId": "SKU-1042", "title": "Volt Runner 2",
  "unitPrice": 198.12, "quantity": 1, "total": 198.12, "currency": "usd",
  "expiresAt": 1760700060000, "orderNumber": "…"
}

Lock status: Active, CheckoutStarted, Completed (bought), Expired or Cancelled. Errors: 401 bad or missing key, 404 not found in this store, 429 too many requests.

Order webhooks

Freefall sends a POST with a JSON body to your endpoint when an order is paid. The endpoint must be https:// on the public internet. Reply with any 2xx within 10 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours (about 2 days in all), then marked failed. You can see recent deliveries on the Embed & API keys page, and send a ping event with Send test event.

{
  "id": "3f0c…",
  "type": "order.paid",
  "created": 1760700042000,
  "data": { /* the order object */ }
}

The order object

Checking signatures

Compute HMAC-SHA256 of t + "." + rawBody with your signing secret, compare it to v1 in constant time, and reject the request if it doesn't match or t is more than 5 minutes old. Use the raw request body, before any JSON parsing.

Node.js (Express)

const crypto = require('crypto');

app.post('/webhooks/freefall', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = Object.fromEntries((req.get('Freefall-Signature') || '').split(',').map(p => p.split('=')));
  const body = req.body.toString('utf8');
  const expected = crypto.createHmac('sha256', process.env.FREEFALL_WEBHOOK_SECRET)
    .update(sig.t + '.' + body).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
  const valid = fresh && sig.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig.v1), Buffer.from(expected));
  if (!valid) return res.status(400).send('Bad signature');

  const event = JSON.parse(body);
  if (event.type === 'order.paid') {
    // Create the order in your system once per event.id
  }
  res.sendStatus(200);
});

Python (Flask)

import hashlib, hmac, os, time

@app.post("/webhooks/freefall")
def freefall():
    body = request.get_data(as_text=True)
    sig = dict(p.split("=", 1) for p in request.headers.get("Freefall-Signature", "").split(",") if "=" in p)
    expected = hmac.new(os.environ["FREEFALL_WEBHOOK_SECRET"].encode(),
                        f"{sig.get('t')}.{body}".encode(), hashlib.sha256).hexdigest()
    if abs(time.time() - int(sig.get("t", 0))) > 300 or not hmac.compare_digest(expected, sig.get("v1", "")):
        return "Bad signature", 400
    event = request.get_json()
    if event["type"] == "order.paid":
        pass  # create the order once per event["id"]
    return "", 200

PHP

$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_FREEFALL_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('FREEFALL_WEBHOOK_SECRET'));
if (abs(time() - (int)($sig['t'] ?? 0)) > 300 || !hash_equals($expected, $sig['v1'] ?? '')) {
    http_response_code(400); exit;
}
$event = json_decode($body, true);
if ($event['type'] === 'order.paid') {
    // create the order once per $event['id']
}
http_response_code(200);

Limits

• Locks: a locked price is held for 1 minute, with up to 3 minutes more if the shopper's bank runs a card check. Each shopper can hold one open lock per store at a time, and repeated locking is limited to keep drops fair.
• API: requests are rate-limited. If you get 429, wait a little and try again.
• Shipping: shoppers can use US and Canadian addresses. Each store handles its own shipping; the locked price is the full amount charged.
• Currencies: USD, CAD, EUR, GBP and AUD, set per store.

If something's wrong