What the API covers
The API exposes the product kinds listed by GET /catalog: game top-ups, gift cards, game keys, Steam Wallet top-up, Steam gift games, Telegram Stars, Telegram Premium and manual services. Each kind has its own recipient parameters — a player ID and server for one game, a Steam login or invite URL for Steam products, a Telegram username for Telegram products — so your integration reads the required fields from the live catalog instead of hard-coding one format.
Authentication uses an API key you create after signing in, sent as a Bearer token or X-API-Key header. Purchases are charged to your prepaid USD reseller balance, which you fund on the platform before ordering. There is no public endpoint for wallet funding, refunds, cancellations, webhooks or ePIN management — those stay in your account area.
Quickstart: from API key to first order
Step 1 — Verify your key. Create an account, open API & Keys in the developer area and issue a key. Call GET /ping with your key to confirm authentication works before writing any ordering code.
Step 2 — Browse products. Call GET /catalog to list supported kinds and their parameter metadata, then GET /products?kind=topups (or another kind) to discover product identifiers. Use the search, limit and offset parameters to page through the catalog.
Step 3 — Check offers and prices. Call GET /offers?kind=topups&id=CATEGORY_ID with a product identifier from the previous step. The response carries your current account selling prices and the recipient metadata (for example which player fields the offer expects). For Telegram Stars, Telegram Premium and Steam top-up, omit the id parameter.
Step 4 — Obtain a quote. POST /quote with the chosen kind, product key, quantity and recipient parameters. A quote validates the request and prices it without charging or reserving anything — use it to show your customer a final price before they pay you.
Step 5 — Submit an order. POST /orders with the same body plus a unique idempotency_key (8–80 characters) per intended purchase. A 201 response means a new order was created and your wallet was charged; a 200 response with duplicate=true means the key was already used and you received the existing order instead of a second charge.
Step 6 — Track fulfillment. Poll GET /orders/{id} every 5–10 seconds until the order reaches a final status: completed, failed, cancelled or refunded. Read codes and delivery data only from a completed order. Failed charged orders are refunded to your wallet by the order workflow; reconcile with GET /transactions.
Safe example requests
List game top-up products: GET https://bulkepin.com/api/public/v1/products?kind=topups&limit=50 with header Authorization: Bearer YOUR_API_KEY.
Read offers for one product: GET https://bulkepin.com/api/public/v1/offers?kind=topups&id=CATEGORY_ID — replace CATEGORY_ID with a real identifier from /products.
Quote a top-up: POST /quote with body {"kind":"topups","product_key":"CATEGORY_ID","quantity":1,"params":{"category_id":"CATEGORY_ID","offer_id":"OFFER_ID","fields":{"player_id":"PLAYER_ID"}}}. Replace every placeholder with live catalog values.
Create the order: POST /orders with the same body plus "idempotency_key":"shop-order-10492". If the request times out, retry with the identical key and body — never invent a new key for the same purchase.
Use quantity 1 for most products; gift cards and game keys accept 1–100, and Telegram Stars takes its count in params.quantity (50–10000). USD amounts are JSON numbers; format them to four decimals for display.
Integrate an online shop
Map your storefront listings to product and offer identifiers from /products and /offers, and refresh prices from the API rather than caching them as permanent rates. When a customer checks out, your server calls /quote to validate the recipient details and price, collects your customer's payment through your own checkout, and only then calls /orders.
Keep your customer payments and your prepaid supplier balance separate in your own records. Your shop remains responsible for its checkout, taxes, customer communication and delivery confirmation; Bulk Epin fulfills the digital product behind your order.
Integrate a Telegram bot
A Telegram bot follows the same server-side workflow from its backend: collect the exact recipient details in the chat (player ID, Steam login or Telegram username depending on the product), validate the selected offer with /quote, submit one intended purchase with /orders and an idempotency key, then poll /orders/{id} and deliver the result to the buyer in chat.
Never place your API key in bot messages, client code or a public repository — the key spends real balance. Bulk Epin provides the ordering API; the bot itself, its payments and its user experience are yours to build.
Rate limits, errors and reliability
The default limit is 60 requests per rolling minute per API key, configurable by the platform administrator. A 429 response includes a Retry-After header (currently 60 seconds) and a retry_after_seconds field — honor it instead of hammering the endpoint.
Error responses use consistent codes: 401 for a missing, invalid or revoked key, 402 insufficient_balance, 403 wallet_blocked, 404 for an unavailable offer or unknown order, 422 for validation errors and 429 for rate limiting. Order statuses are pending, processing, completed, failed, cancelled and refunded. A successful HTTP response alone is not proof of delivery — always read the order status.
Frequently asked questions
How do I get an API key?
Create a reseller account, sign in and open API & Keys in the developer area. You can issue and revoke keys there, and each key has its own request limit shown in the admin settings.
How are orders paid for?
Orders are charged to your prepaid USD reseller balance at the moment you create them. Top up the balance in your account first; a 402 insufficient_balance response means the wallet cannot cover the quoted total.
Is it safe to retry a failed request?
Yes, if you reuse the same idempotency_key and request body. The API returns the original order with duplicate=true instead of charging you twice. Never retry a payment request with a new key after a timeout — the first attempt may have been accepted.
Do products have regional restrictions?
Yes. Region, currency and recipient requirements vary by product and offer — for example Steam Wallet codes and game keys can be region-locked. Read the current offer metadata from /offers before ordering and never assume one game's format applies to another.
Can I put the API key in my website's JavaScript or mobile app?
No. Make all authenticated calls from your own server or bot backend. A key exposed in browser code or an app bundle can be used by anyone to spend your balance.
Does the API support webhooks or automatic refunds?
No public webhook, cancellation, refund or wallet-funding endpoint is provided. Poll GET /orders/{id} for status; failed charged orders are refunded to your wallet by the order workflow, and GET /transactions lists the wallet history.