Selley Developer Docs

Quick start

1. 1Create an API key in Dashboard → Settings → Security. Copy the secret once — it is shown only at creation time.
2. 2Set your base URL to https://selley.io/api/v1 (or your custom domain with /api/v1).
3. 3Send a test request — list your live products to confirm authentication works.
4. 4Subscribe to webhooks in Developers → Webhooks so your backend reacts to orders and fulfillment in real time.

curl "https://selley.io/api/v1/products?limit=5" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Product types

Fulfillment & delivery

Mystery box fairness

What buyers see before purchase

• Drop table — Each outcome, weight, percentage chance, and remaining stock.
• Fairness commitment — SHA-256(server seed) published before checkout. The seller cannot change the seed without changing this hash.
• Pool version — Increments when odds or stock change, with a new commitment. Buyers should note version + hash at purchase time.
• Optional client seed — Buyers may set __mysteryClientSeed so part of the randomness comes from them.

Why the commitment hash matters

Verification

shown_before_purchase === SHA-256(revealed_server_seed)

How rolls work

1. Resolve client seed from __mysteryClientSeed or generate one.
2. Assign a unique nonce per open (per quantity index).
3. Compute proofHash = HMAC-SHA256(serverSeed, clientSeed + ":" + nonce).
4. Derive roll index: parseInt(proofHash[0..12], 16) mod totalWeight where totalWeight is the sum of weights for in-stock outcomes.
5. Walk outcomes in order; the roll selects exactly one item matching published weights.
6. A second HMAC pass picks which deliverable code from that outcome's stock.

const crypto = require("crypto");

function rollHash(serverSeed, clientSeed, nonce) {
  return crypto.createHmac("sha256", serverSeed)
    .update(`${clientSeed}:${nonce}`)
    .digest("hex");
}

function rollIndex(proofHash, totalWeight) {
  return parseInt(proofHash.slice(0, 13), 16) % totalWeight;
}

Verify after opening

• Revealed server seed hashes to the pre-purchase commitment.
• Proof hash matches HMAC-SHA256(server seed, client seed + nonce).
• Roll index maps to the won item using the weight snapshot stored on the order line.
• Delivered code matches the second HMAC selection for that outcome's stock.

Pre-purchase checklist

Overview

Webhooks send a POST request to a URL you provide whenever certain events occur (e.g. order paid, product updated, subscription renewed). Configure webhooks in the dashboard under Developers → Webhooks: add your endpoint URL and select which events to subscribe to. At least one event must be selected per webhook.

Each request includes a JSON body with event, data (detailed payload), timestamp, and source. Your endpoint should respond with 2xx to acknowledge receipt. Non-2xx responses are logged and may be retried.

Event types

Events are grouped by category. Select the events you need when creating a webhook. The data object structure depends on the event category (see Payload structure below).

Request format

Every webhook is sent as POST to your URL with the following headers and body.

Headers

Top-level body fields

Your endpoint should respond with HTTP 200–299 to acknowledge receipt. Timeout is 15 seconds. Failed or non-2xx deliveries are logged in Developers → Webhook Logs where you can retry or view the payload.

Payload structure

The data object in each webhook is detailed and depends on the event category. Below are the full structures for Order, Subscription, Product, Query, and Feedback. All monetary values use the order/product currency; timestamps are Unix seconds unless noted.

{
  "event": "order:paid",
  "data": { /* see Order data below */ },
  "timestamp": "2024-06-15T14:32:00.000Z",
  "source": "selley"
}

Order data

For all order:* events, data includes order details, customer, product, gateway, fees, IP/location, status history, delivery info, and nested product block.

{
  "id": 238987,
  "uniqid": "593fe6-bd6c461fa4-f713f6",
  "type": "PRODUCT",
  "origin": "EMBED",
  "total": 45.77,
  "total_display": "33.99",
  "currency": "USD",
  "shop_id": 5436,
  "customer_email": "[email protected]",
  "customer_id": "cst_xxx",
  "product_id": "6894accbf05b6",
  "product_title": "Semi-Annual Alpha Package",
  "product_type": "SERVICE",
  "quantity": 1,
  "custom_fields": {
    "Discord ID": "User#1234",
    "Account Name": "AlphaUser"
  },
  "subscription_id": null,
  "gateway": "STRIPE",
  "status": "COMPLETED",
  "discount": 0,
  "fee_percentage": 4,
  "country": "GB",
  "ip": "2a00:23c7:...",
  "ip_info": { "country_code": "GB", "city": "London", "ISP": "...", "vpn": 0, "proxy": 0 },
  "created_at": 1772131826,
  "updated_at": 1772131943,
  "status_history": [...],
  "gateway_data": { "type": "STRIPE", "label": "Stripe", "payment_reference": "pi_xxx" },
  "product": { "uniqid": "...", "title": "...", "price_display": "...", "currency": "...", ... },
  "products": [{ "uniqid": "...", "title": "...", "quantity": 1, "price": 45.77, "currency": "USD" }],
  "delivery_info": { "downloads": [], "license_keys": [], "external_urls": [...], "tracking_codes": [] },
  "total_conversions": { "USD": 45.77, "EUR": "39.38", "crypto": { "BTC": "...", "ETH": "..." } }
}

Subscription data

For subscription:* events, data includes which product, amount, billing interval, subscription and Stripe IDs, period dates, trial info, and customer.

Product data

For product:created, product:edited, product:deleted, product:stock, product:stock:low, product:dynamic, data includes product details, pricing, stock, gateways, and metadata.

Mystery box data

For product:mystery:revealed, Selley fires after provably fair rolls complete for a mystery box line item. The webhook data identifies the order and product; full outcome details (rolled item, commitment hash, server seed, roll proof) are stored on the order item and returned on the customer invoice and order APIs.

{
  "event": "product:mystery:revealed",
  "data": {
    "orderId": "clxord123",
    "orderNumber": "ORD-48291",
    "productId": "rec_mystery01",
    "productName": "Premium Case"
  },
  "timestamp": "2024-06-15T14:32:00.000Z",
  "source": "selley"
}

Dynamic fulfillment data

The INVOICE.ITEM.DELIVER-DYNAMIC event is sent to the Dynamic Webhook URL configured on individual dynamic products. This payload is extremely rich and provides full context for the order, the customer (including custom fields), and the specific line item.

{
  "event": "INVOICE.ITEM.DELIVER-DYNAMIC",
  "id": "ord_238987",
  "order_number": "ORD-SELLEY-1234",
  "coupon_id": "cpn_555",
  "coupon_discount": "5.00",
  "gateway_fee": "0.45",
  "shop_customer_id": "cst_888",
  "created_at": "2024-06-15T14:32:00.000Z",
  "updated_at": "2024-06-15T14:32:10.000Z",
  "gateway": "STRIPE",
  "email": "[email protected]",
  "status": "completed",
  "price": "45.00",
  "currency": "USD",
  "amount": 1,
  "custom_fields": {
    "Discord ID": "User#0001",
    "Special Instructions": "Please deliver via API"
  },
  "customer": {
    "id": "cst_888",
    "email": "[email protected]",
    "name": "John Doe",
    "discord_id": "000000000000000000",
    "discord_username": "john_doe"
  },
  "coupon": {
    "id": "cpn_555",
    "code": "SAVE5",
    "discount": "5.00",
    "type": "fixed"
  },
  "item": {
    "id": "itm_999",
    "invoice_id": "ord_238987",
    "product_id": "prod_777",
    "status": "completed",
    "price": "45.00",
    "quantity": 1,
    "total_price": "45.00",
    "custom_fields": { ... },
    "product": {
      "id": "prod_777",
      "name": "Dynamic Service X"
    }
  }
}

Query & Feedback data

Query (query:created, query:replied): data includes id, ticket_id, shop_id, customer_email, customer_id, subject, message, status, reply_count, created_at, updated_at.

Feedback (feedback:received): data includes id, shop_id, product_id, product_title, order_id, customer_email, rating, comment, created_at.

Logs & Simulator

In the dashboard, Developers → Webhook Logs shows every delivery attempt: URL, event, response status, retry count, and created time. You can Send again to retry a failed delivery or open Payload to view the exact JSON that was sent.

Use the Simulator to send a test webhook to a configured URL: choose a webhook and an event, then trigger a delivery. The payload will match the structure documented above (with sample data). This helps verify your endpoint and payload handling without creating real orders or subscriptions.

Overview

The Embed lets you place a product or bundle (group) checkout on any external website. Customers see your product, choose quantity, and complete payment without leaving the host site. The flow is a modal that opens from your embed script; checkout and payment happen inside the modal.

Generate your embed code in the dashboard under Developers → Embed: select a product or group, optionally set button text and styles, then copy the script and HTML snippet. Add them to your site where you want the button to appear.

Usage

Include the Selley embed script on your page, then add a button or link with data-selley-store, and for a single product data-selley-product (product ID from your store), or for a bundle data-selley-group (group ID). When the user clicks, a modal opens with the product/group details and a gateway selection that leads to full checkout. No redirect to Selley is required; the flow stays in the modal.

Example: single product

<script src="https://your-domain.com/embed.js" async></script>
<button data-selley-store="your-store" data-selley-product="rec_abc123">
  Buy now
</button>

Example: bundle (group)

<button data-selley-store="your-store" data-selley-group="group_xyz">
  Buy bundle
</button>

Your store subdomain (e.g. your-store.myselley.com) or custom domain is used as the base. The embed script and CSS URL are shown in the dashboard Embed page.