Reseller API: act as your customers

The reselling guide's loop runs everything through YOUR account and tags plans with labels. Approved resellers get a stronger model: your key names one of your customers per request, and the call runs as that customer: their own plans, their own spendable balance, their own order history, fully isolated from every other customer. You price in your business dashboard, we charge you your negotiated rates, and your customers never see us anywhere.

Reseller access is granted, not self-served: apply at hproxy.com/white-label. Approval provisions your rate card and a reseller API key carrying the act_as_reseller_customer scope, and opens your business dashboard (balance, statement, customers, your prices, storefront, support inbox).

Naming a customer

Add one header to any /api/v1 call. The id is yours (your user id, an email hash, anything stable): up to 64 characters of letters, digits, _, -, .. It is scoped to your account, so two businesses using the same id refer to different people and can never see each other's data. The customer is created the first time you name one, so there is no signup call.

curl https://hproxy.com/api/v1/plans \
  -H "X-API-Key: hpx_your_key_here" \
  -H "X-Reseller-Customer-Id: user-4021"

Without the header, the same key acts as your own account (your wallet, your deposits), which is how you top up your reseller balance. With it, reads and writes belong to that customer.

How the money works

Your customers pay you, on your site, with your payment methods. You mirror what they paid you as store credit on that customer (from your business dashboard), and their orders spend that credit at your prices while your prepaid reseller balance is charged your negotiated rate in the same transaction. The gap is your margin, and it never appears in anything their side can read. When their credit is short an order fails with 402 customer_credit_insufficient; when your balance is short, 402 reseller_balance_insufficient — nothing half-charges. POST /deposits is refused for a named customer (deposits_not_available): there is deliberately no payment page of ours for your customers to reach.

curl https://hproxy.com/api/v1/customer \
  -H "X-API-Key: hpx_your_key_here" \
  -H "X-Reseller-Customer-Id: user-4021"

curl -X PUT https://hproxy.com/api/v1/customer/contact \
  -H "X-API-Key: hpx_your_key_here" \
  -H "X-Reseller-Customer-Id: user-4021" \
  -H "Content-Type: application/json" \
  -d '{"email": "alex@example.com", "label": "Alex M."}'

curl "https://hproxy.com/api/v1/customers?limit=50" \
  -H "X-API-Key: hpx_your_key_here"

The whole loop, as one customer

# 0. Your customer signs up on YOUR site -> create + identify them
curl -X PUT https://hproxy.com/api/v1/customer/contact \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \
  -H "Content-Type: application/json" \
  -d '{"email": "alex@example.com", "label": "Alex M."}'

# 1. They paid you -> issue the credit in your business dashboard
#    (Customers -> user-4021 -> Add credit). Their balance:
curl https://hproxy.com/api/v1/wallet \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021"
# -> { "balanceCents": 2500, "currency": "USD" }  (their credit, your prices)

# 2. They buy on your site -> order AS them (Idempotency-Key is REQUIRED here)
curl -X POST https://hproxy.com/api/v1/orders \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \
  -H "Idempotency-Key: your-order-83741" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "residential-lite", "quantity": 5}'

# 3. Deliver: generate lines from THEIR plan (free, repeatable)
curl https://hproxy.com/api/v1/plans \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021"
curl -X POST https://hproxy.com/api/v1/plans/{planId}/generate \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \
  -H "Content-Type: application/json" \
  -d '{"count": 100, "country": "US", "stickyMinutes": 10}'

Dedicated IPs work the same way: list the countries in stock with GET /products/{id}/options (always current — sold-out countries drop out on their own), quote and order with country and period_days in fulfillment_meta while naming the customer, then GET /proxies?order_id=… as that customer once the order completes. Renewals too: the ids must belong to the acting customer, exactly as ownership works everywhere else.

Rules the lane enforces

An Idempotency-Key is required on every reseller order (a plain key merely should send one; a reseller key must, and an order without one is refused before any charge): only your system knows whether a request is a new sale or a retry, and this is what makes retries free. Isolation is structural: a customer id that is not yours simply does not resolve, plan and proxy ownership follow the acting customer, and GET /plans for customer A can never show customer B's plans. Reseller keys also carry a higher rate-limit tier, sized for a whole storefront (thousands of customers behind one key) rather than a single integration, so a busy shop or a bulk operation is never throttled for being busy.