Item types

def effective_price_cents(item: dict, has_active_subscription: bool) -> int:
    """The per-unit price your balance will actually be charged, in cents."""
    if has_active_subscription:
        return item["subscriber_price"]
    return item["price"]
def estimate_charge(item: dict, quantity: float, has_active_subscription: bool = False) -> float:
    """Estimated charge for an order, in major units (e.g. dollars)."""
    return quantity * effective_price_cents(item, has_active_subscription) / 100
# `item` is a record read from the catalog snapshot (see the Catalog guide)
print(f"1 unit costs {item['price'] / 100:.2f}")
print(f"5 units cost {estimate_charge(item, 5):.2f}")

import requests
BASE = "https://api.voodoo.center"
headers = {"Authorization": f"Bearer {access_token}"}
# `item` is a `key` record from the catalog, e.g. Amazon Gift Card 25 TRY
wanted = 3
assert item["product_type"] == "key" and item["in_stock"]
assert item["min_quantity"] <= wanted <= item["max_quantity"]
print(f"Expected charge: {wanted * item['price'] / 100:.2f}")
order = requests.post(f"{BASE}/v1/orders", headers=headers, json={
    "item_id": item["id"],
    "quantity": wanted,                    # integer count of codes
    "merchant_order_id": "keys-2026-0001", # your idempotency key
}).json()
print(order["id"], order["status"])        # ... pending — the codes arrive
                                           # on your webhook

@app.post("/webhooks/voodoo-center")
async def voodoo_webhook(request: Request):
    # 1. Verify X-Signature against the RAW body, and dedupe on order_id —
    #    see the Webhooks guide for the full receiver.
    event = await request.json()
    # 2. Correlate via merchant_order_id and collect the codes.
    if event["codes"]:                         # `completed` or `partial`
        store_codes(event["merchant_order_id"], event["codes"])
    if event["delivered_quantity"] < event["quantity"]:
        # `partial` (or `failed`): the undelivered codes were refunded
        record_refund(event["merchant_order_id"], event["refund_amount"])
    return {"ok": True}                        # ack fast; heavy work async

def rate_per_dollar(item: dict, price_cents: int | None = None) -> float:
    """How much target currency $1 buys. Pass subscriber_price to see your
    subscription rate."""
    price = price_cents if price_cents is not None else item["price"]
    return item["amount_per_price"] / price * 100
def charge_for(item: dict, quantity: float) -> float:
    """What an order of `quantity` costs, in major units."""
    return quantity * item["price"] / 100
def delivered_for(item: dict, quantity: float) -> float:
    """How much target currency an order of `quantity` delivers."""
    return quantity * item["amount_per_price"]
def quantity_for(item: dict, target_amount: float) -> float:
    """The `quantity` to send so the customer receives `target_amount` units.
    Raises if the item can't deliver that amount in one order."""
    quantity = target_amount / item["amount_per_price"]
    if not item["min_quantity"] <= quantity <= item["max_quantity"]:
        raise ValueError(
            f"quantity {quantity} outside "
            f"{item['min_quantity']}..{item['max_quantity']}"
        )
    return quantity
# item = {"price": 100, "amount_per_price": 110, "min_quantity": 1, "max_quantity": 500, ...}
print(f"Rate: {rate_per_dollar(item):g} units per $1")        # 110
print(f"550 units -> quantity {quantity_for(item, 550):g}, "  # 5
      f"charge {charge_for(item, quantity_for(item, 550)):.2f}")

import requests
BASE = "https://api.voodoo.center"
headers = {"Authorization": f"Bearer {access_token}"}
# `item` is a `topup` record from the catalog, e.g. Steam Top-up (USD)
target_amount = 20  # what the customer should receive
quantity = quantity_for(item, target_amount)
print(f"Charging {charge_for(item, quantity):.2f} "
      f"to deliver {delivered_for(item, quantity):g} units")
order = requests.post(f"{BASE}/v1/orders", headers=headers, json={
    "item_id": item["id"],
    "quantity": quantity,                     # decimal, required for topup
    "merchant_order_id": "topup-2026-0001",
    "fields": {
        "steam_login": "customer_login",      # the item's required fields,
    },                                        # keyed by field *name*
}).json()
print(order["id"], order["status"], order["price"])  # charge in major units

import json
import lmdb
env = lmdb.open("catalog.lmdb", subdir=False, readonly=True, lock=False)
topups = []
with env.begin() as txn:
    for _key, value in txn.cursor():
        item = json.loads(value)
        if item["product_type"] == "topup" and item["in_stock"]:
            topups.append(item)
for item in sorted(topups, key=rate_per_dollar, reverse=True)[:10]:
    print(f"{rate_per_dollar(item):>10.2f} units/$1  "
          f"{item['id']}  {item['name']}")

import requests
BASE = "https://api.voodoo.center"
headers = {"Authorization": f"Bearer {access_token}"}
# `item` is a `service` record from the catalog, e.g. PUBG direct top-up
assert item["product_type"] == "service" and item["in_stock"]
print(f"This service costs {item['price'] / 100:.2f}")
# Build `fields` from the record's form definition
body_fields = {}
for field in item["fields"]:
    if field["type"] == "choice":
        # send the numeric id of the chosen option, not the label
        body_fields[field["name"]] = field["options"][0]["id"]
    else:
        body_fields[field["name"]] = "<value from your customer>"
order = requests.post(f"{BASE}/v1/orders", headers=headers, json={
    "item_id": item["id"],                    # no `quantity` for services
    "merchant_order_id": "svc-2026-0001",
    "fields": body_fields,
}).json()
print(order["id"], order["status"])