Buy decorations from your own bot or site

Orders are paid from your account balance at your reseller price and delivered automatically. Poll the order until it has a gift_link.

Authentication

Make a key on your account page (resellers only). It is shown once; making a new one stops the old one. Send it on every request:

Authorization: Bearer dsr_your_key

Base URL: https://decors.bid. Keep the key secret — anyone with it can spend your balance. Requests are rate limited per key; a 429 answer has retry_after (seconds).

Endpoints

	Path	What it does
GET	`/api/v1/me`	Your account, balance and pricing plan
GET	`/api/v1/catalog`	Every SKU with your price
POST	`/api/v1/orders`	Buy one SKU from your balance
GET	`/api/v1/orders`	Your orders, newest first (`?page=`, 50 per page)
GET	`/api/v1/orders/{order_id}`	One order (status, gift link)

Buy

curl -X POST https://decors.bid/api/v1/orders \
  -H "Authorization: Bearer dsr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sku": "1212569433839636530", "reference": "order-1001"}'

sku: the item's SKU id (colour variants have their own SKU — see the catalog). reference (optional, recommended): your own id, 1–64 of A-Z a-z 0-9 _ . - :. Sending the same reference again returns the same order with "duplicate": true — you are never charged twice, so retrying after a timeout is safe.

201 Created
{
  "order": {
    "order_id": "ds_1793520000_1a2b3c4d",
    "reference": "order-1001",
    "sku": "1212569433839636530",
    "name": "Cat Ears",
    "color": "Yellow",
    "price_usd": 1.95,
    "status": "queued",
    "queue_position": 2,
    "eta_seconds": 140,
    "gift_link": null,
    "created_at": 1793520000000,
    "delivered_at": null
  },
  "duplicate": false
}

Wait for the gift

Poll GET /api/v1/orders/{order_id} every 10–20 seconds until status is final.

status	meaning
`queued`	Paid, waiting its turn (`queue_position`, `eta_seconds`)
`processing`	Being bought right now
`delivered`	Done — `gift_link` is set (final)
`delivered_test`	The shop is in test mode: nothing was bought (final)
`refunded`	Could not be bought; the price went back to your balance (final)
`failed` / `needs_review`	Stuck — contact support with the `order_id`

Errors

Every error is {"error": "<code>", "detail": "<text>"}.

HTTP	error	when
401	`unauthorized`	Missing / wrong key, or no longer a reseller
402	`insufficient_balance`	Top up first (also returns `balance_usd`, `price_usd`)
404	`not_for_sale` / `not_found`	Unknown SKU / not your order
400	`bad_sku` / `bad_reference`	Malformed input
429	`rate_limited`	Too many calls; wait `retry_after` seconds
503	`closed`	The shop is paused; try later

Python example

import time, requests

BASE = "https://decors.bid"
H = {"Authorization": "Bearer dsr_your_key"}

r = requests.post(f"{BASE}/api/v1/orders", headers=H,
                  json={"sku": "1212569433839636530", "reference": "order-1001"}, timeout=30)
r.raise_for_status()
order = r.json()["order"]
while order["status"] in ("queued", "processing"):
    time.sleep(15)
    order = requests.get(f"{BASE}/api/v1/orders/{order['order_id']}", headers=H, timeout=30).json()["order"]
print(order["status"], order["gift_link"])