> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voodoo.center/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voodoo.center/_mcp/server.

# Introduction

The Voodoo Center API lets you buy digital goods — gift-card keys, top-ups and
game services — from your own systems. You create an order, we charge your
account balance, fulfillment runs asynchronously, and the result is delivered to
your webhook (and is always readable back from the API).

## Base URL

All API requests go to a single host:

```
https://api.voodoo.center
```

Authentication endpoints share the same host under `/api/v1/auth`.

## What the API can do

The programmatic API is intentionally small — three endpoints:

| Capability                 | Endpoint                      |
| -------------------------- | ----------------------------- |
| Check your account balance | `GET /api/v1/account/balance` |
| Place an order             | `POST /api/v1/orders`         |
| Look up an order           | `GET /api/v1/orders/{id}`     |

Everything else — catalog browsing, favorites, deposits, tickets, team and
subscription management, and **listing** orders — lives in the dashboard and is
**not** part of the programmatic API. Discover the `item_id`, product type,
quantity bounds and input fields you need for an order from the **catalog
export** (a separate data feed, not an API endpoint).

## How ordering works

`POST /api/v1/orders` charges your balance and returns immediately with
`201` and `status: "pending"`. Fulfillment then runs in the background, and the
order settles on a terminal status:

* **`completed`** — fully delivered. For key items, `codes` holds the delivered
  key strings.
* **`partial`** — some units delivered; `refund_amount` is the refund for the
  undelivered portion.
* **`failed`** — nothing delivered; the charge is refunded and `error` /
  `error_message` explain why.

You learn the terminal result in two ways: your **webhook** (recommended — push,
no polling) or by reading `GET /api/v1/orders/{id}`. See
[Placing orders](/orders) and [Webhooks](/webhooks) for the full flow.

## Quickstart

In the dashboard, open the **API** page and create a key. The raw key
(format `ak_...`) is shown **once** — copy it immediately.

Trade your `ak_` key for a short-lived Bearer token (valid **2 hours**):

```bash title="Exchange your API key"
curl -X POST https://api.voodoo.center/api/v1/auth/token/client \
  -H "Content-Type: application/json" \
  -d '{"api_key":"ak_your_api_key_here"}'
```

```json title="Response"
{
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...",
  "token_type": "Bearer"
}
```

Send the token as a Bearer credential on every API call:

```bash title="Place an order"
curl -X POST https://api.voodoo.center/api/v1/orders \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"item_id": 4090, "quantity": 2, "merchant_order_id": "po-10231"}'
```

You get back `201` with `status: "pending"`. Watch for the terminal status on
your webhook, or poll `GET /api/v1/orders/{id}`.

For the full end-to-end flow — including configuring and verifying your
webhook — follow the [Quickstart](/quickstart).

## Try it in your browser

The **[API Reference](/api-reference)** tab includes an interactive **API
Explorer** ("try it") for every endpoint. You don't need to build the auth flow
by hand: enter **only your `ak_` API key** once, and the Explorer automatically
exchanges it for a Bearer access token and attaches it to your requests. There's
no JWT to copy or paste.

Key → token → order → webhook, end to end, with copy-paste cURL.

Turn your `ak_` key into a Bearer token and keep it fresh.

Item types, fields, quantity rules and the order lifecycle.

Receive and verify terminal-status events for your orders.

The error envelope, status codes and failure semantics.