Reseller API

Account

Your wallet balance, your rate for every plan, and how many proxies you currently hold.

curl -H "Authorization: Bearer $KEY" \
  https://whitecloakproxy.com/api/reseller/v1/account

{
  "success": true,
  "name": "Partner Site",
  "balance_cents": 130000,
  "price_per_proxy_cents": 7350,
  "commission_pct": 25,
  "pricing": [
    { "duration": "daily",    "days": 1,  "price_cents": 600,  "retail_cents": 800 },
    { "duration": "3day",     "days": 3,  "price_cents": 1500, "retail_cents": 2000 },
    { "duration": "weekly",   "days": 7,  "price_cents": 2625, "retail_cents": 3500 },
    { "duration": "biweekly", "days": 14, "price_cents": 4500, "retail_cents": 6000 },
    { "duration": "monthly",  "days": 30, "price_cents": 7350, "retail_cents": 9800 }
  ],
  "pricing_by_carrier": {
    "T-Mobile": [ /* same shape, that carrier's exact rates */ ],
    "Verizon":  [ /* ... */ ]
  },
  "active_proxies": 12,
  "max_active_proxies": null,
  "billing_mode": "wallet"
}

• ◆Read your prices from here rather than hardcoding them. price_cents is what you pay; retail_cents is our public price it was derived from.
• ◆commission_pct is the share of retail you keep: every plan is priced as retail x (100 - commission_pct) / 100, so if our retail moves your rate follows and your margin holds. Fixed-rate accounts have commission_pct: null and one price for all plans.
• ◆pricing is the rate when a purchase names no carrier. Such an order can be filled from any carrier, so it's priced at the highest carrier rate for that plan. Name a carrier to get the exact rate in pricing_by_carrier.
• ◆price_per_proxy_cents is kept for older integrations and equals the monthly, any-carrier rate.
• ◆All prices everywhere in this API are US cents: 7350 means $73.50.
• ◆Watch balance_cents and top up with us before it runs low; purchases fail cleanly with 402 when it can't cover them.
• ◆billing_mode is either "wallet" (the default, prepaid balance above) or "card" (pay-per-order, see the Purchase endpoint's card billing note). Card accounts always report balance_cents: null here and add a card block: { "last4": "4113", "brand": "VISA" }.

Inventory

Live purchasable stock, grouped by carrier and US state. Counts refresh continuously.

curl -H "Authorization: Bearer $KEY" \
  https://whitecloakproxy.com/api/reseller/v1/inventory

{
  "success": true,
  "total_available": 37,
  "stock": [
    { "carrier": "T-Mobile", "state": "FL", "count": 9 },
    { "carrier": "T-Mobile", "state": "NY", "count": 14 },
    { "carrier": "Verizon",  "state": "NY", "count": 8 },
    { "carrier": "Verizon",  "state": "TX", "count": 6 }
  ]
}

• ◆Stock can sell out between a check and a purchase, and you'd get a clean 409, never a wrong proxy.

Purchase

Buy 1–20 proxies in one call. carrier and state are guarantees: every delivered proxy matches them, or the call fails before anything is charged.

curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 2,
    "duration": "weekly",
    "carrier": "Verizon",
    "state": "NY",
    "idempotency_key": "your-order-8841"
  }' \
  https://whitecloakproxy.com/api/reseller/v1/purchase

{
  "success": true,
  "purchased": [
    {
      "proxy_id": "1f6f2a34-....",
      "carrier": "Verizon",
      "state": "NY",
      "host": "relay7.pprx.io",
      "password": "kJ2mPq9xL4",
      "http":   { "port": 10412, "username": "u_8842_http" },
      "socks5": { "port": 10413, "username": "u_8842_s5" },
      "rotation_url": "https://pprx.io/r/AbC123xYz",
      "auto_rotate_minutes": 0,
      "auto_renew": false,
      "expires_at": "2026-08-04T18:20:11.000Z"
    }
  ],
  "failed_count": 0,
  "duration": "weekly",
  "duration_days": 7,
  "unit_price_cents": 2625,
  "charged_cents": 5250,
  "balance_cents": 124750
}

• ◆Always send an idempotency_key (e.g. your internal order ID). If your request times out and you retry with the same key, you get the original result back instead of being charged twice. A retry while the original is still processing returns 409. Wait and retry again.
• ◆Use a generous HTTP timeout (120s+): provisioning happens live, one device at a time.
• ◆Store proxy_id. It's the handle for extend and reset-password.
• ◆failed_count > 0 means some units couldn't be provisioned and were refunded automatically; purchased contains only real, working proxies.
• ◆duration sets both how long the proxy lasts and what you're charged. See pricing on the Account endpoint. Omit it and you get a 30-day proxy at the monthly rate.
• ◆Card billing (opt-in): card payments are processed by Intuit Payments Inc. (QuickBooks Payments). Accounts with billing_mode "card" skip the wallet entirely. We send you a one-time save-card link. Card details are entered and tokenized client-side and never touch our servers, and every purchase after that charges the saved card directly, settling instantly. For these accounts balance_cents is always null and the response adds a payment block that doubles as your per-transaction receipt: { "method": "card", "charge_id": "MT1a2b3c4d", "last4": "4113", "paid_at": "<ISO timestamp>", "processed_by": "Intuit Payments Inc." }.
• ◆Card billing errors (billing_mode "card" only): 402 { "error": "No card on file. Save a card via your setup link before purchasing." } if you haven't saved a card yet; 402 with a card-specific reason (e.g. "Your card was declined. Please try a different card or contact your bank." or "Your card has expired. Please update your card details.") on a definitive decline; 502 { "error": "Payment status unknown, don't retry; contact support before trying again." } if we couldn't confirm the outcome after a timeout, or a plain 5xx if Intuit's payment_unavailable. In either 5xx case, don't retry blindly; contact support first.
• ◆Card billing partial failures: if some (not all) units fail to provision after a successful card charge, exactly one partial refund is issued automatically. refund_pending_cents plus a warning only appear if that refund itself failed (rare, our team is alerted), the same convention as the wallet path's refund_pending_cents.

List proxies

Every active (unexpired) proxy you hold, soonest-expiring first. Same unit shape as the purchase response.

curl -H "Authorization: Bearer $KEY" \
  https://whitecloakproxy.com/api/reseller/v1/proxies

{
  "success": true,
  "count": 12,
  "proxies": [ { "proxy_id": "...", "expires_at": "...", ... } ]
}

• ◆Poll this daily and renew anything expiring within a day or two, or turn on auto-renew per proxy and let us do it. Expired proxies are released back to the pool and can't be recovered.
• ◆auto_renew and auto_rotate_minutes show each proxy's current settings, so you can read them back after changing them.

Extend

Renew one proxy on the plan of your choice. Extending early never loses time: the new period stacks onto the current expiry.

curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy_id": "1f6f2a34-....", "duration": "weekly"}' \
  https://whitecloakproxy.com/api/reseller/v1/proxies/extend

{
  "success": true,
  "proxy_id": "1f6f2a34-....",
  "expires_at": "2026-08-11T18:20:11.000Z",
  "duration": "weekly",
  "duration_days": 7,
  "unit_price_cents": 2625,
  "charged_cents": 2625,
  "balance_cents": 122125
}

• ◆Omit duration and the proxy renews on the same plan your customer already has, so a weekly proxy renews for another week at the weekly rate. Pass one explicitly to move a customer between plans.
• ◆Send one extend per proxy at a time: if two race, the second is detected, refunded, and answered with 409. Treat that as "already extended" and re-check GET /proxies.
• ◆A 410 means the proxy already expired and was released, and it can't be brought back.

Reset password

Generate a fresh password for one proxy. HTTP and SOCKS5 both switch within about a second. Use it when handing a proxy to a different end customer.

curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy_id": "1f6f2a34-...."}' \
  https://whitecloakproxy.com/api/reseller/v1/proxies/reset-password

{
  "success": true,
  "proxy_id": "1f6f2a34-....",
  "password": "nEw9pAsS2q"
}

Custom login and password

Set your own username and/or password on a proxy instead of the generated ones. Live on HTTP and SOCKS5 within about a second.

curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "proxy_id": "1f6f2a34-....",
    "http_username": "acme_ny_01",
    "socks5_username": "acme_ny_01s",
    "password": "s3cret-pass"
  }' \
  https://whitecloakproxy.com/api/reseller/v1/proxies/credentials

{
  "success": true,
  "proxy_id": "1f6f2a34-....",
  "http":   { "username": "acme_ny_01",  "password": "s3cret-pass" },
  "socks5": { "username": "acme_ny_01s", "password": "s3cret-pass" }
}

• ◆Send any one field or several. Anything you leave out keeps its current value.
• ◆Letters, numbers and - _ . ~ only. Anything else breaks user:pass@host URLs and host:port:user:pass lists, so it's refused up front.
• ◆Usernames are unique across our whole network, so the HTTP and SOCKS5 ports each need their own, and a name someone else already has returns 409. Prefix them with your brand to avoid collisions.
• ◆If one port accepts the change and the other refuses it, the error response still lists the credentials that are live on each port right now.
• ◆POST /proxies/reset-password still works afterwards and puts a fresh generated password on both ports.

Auto-rotation interval

Rotate a proxy's IP automatically on a timer, from every 2 minutes to once a day.

curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy_id": "1f6f2a34-....", "minutes": 10}' \
  https://whitecloakproxy.com/api/reseller/v1/proxies/auto-rotate

{
  "success": true,
  "proxy_id": "1f6f2a34-....",
  "auto_rotate_minutes": 10
}

• ◆The rotation_url keeps working with auto-rotation on, so your customer can still force a new IP between scheduled ones.
• ◆Each rotation drops open connections for a few seconds while the phone reconnects to the carrier.

Auto-renew

Have a proxy renewed automatically before it expires, on its current plan at your rate, paid from your wallet.

curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy_id": "1f6f2a34-....", "enabled": true}' \
  https://whitecloakproxy.com/api/reseller/v1/proxies/auto-renew

{
  "success": true,
  "proxy_id": "1f6f2a34-....",
  "auto_renew": true,
  "expires_at": "2026-08-11T18:20:11.000Z",
  "renews_within_hours_of_expiry": 3
}

• ◆We check every hour and renew anything with auto-renew on that expires in the next 3 hours. Renewing early never loses time, the new period stacks onto the current expiry, same as calling extend yourself.
• ◆It renews on the plan the proxy is on now, so a weekly proxy renews for another week at your weekly rate. To move a customer to another plan, call extend with that duration once and auto-renew follows from then on.
• ◆If your balance can't cover a renewal, we retry on every hourly run until the proxy expires. Top up in that window and it still renews. After expiry it's released like any other lapsed proxy.
• ◆Auto-renew charges your wallet, so watch balance_cents on GET /account the same way you would for manual renewals.

IP whitelist: read

The IP addresses allowed to use a proxy without a username or password.

curl -H "Authorization: Bearer $KEY" \
  "https://whitecloakproxy.com/api/reseller/v1/proxies/whitelist?proxy_id=1f6f2a34-...."

{
  "success": true,
  "proxy_id": "1f6f2a34-....",
  "ips": ["203.0.113.7", "198.51.100.0/24"],
  "enabled": true,
  "max_entries": 20
}

IP whitelist: set

IP authorization. Requests from the listed addresses use the proxy's HTTP and SOCKS5 ports with no login. Everyone else still needs the username and password.

curl -X PUT \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy_id": "1f6f2a34-....", "ips": ["203.0.113.7", "198.51.100.0/24"]}' \
  https://whitecloakproxy.com/api/reseller/v1/proxies/whitelist

{
  "success": true,
  "proxy_id": "1f6f2a34-....",
  "ips": ["203.0.113.7", "198.51.100.0/24"],
  "enabled": true
}

• ◆This replaces the whole list. To add one address, read the list, append, and send it back.
• ◆Ranges can't be broader than /16 for IPv4 or /32 for IPv6, since anyone inside a wider range could use the proxy with no password. Loopback, multicast and 0.0.0.0 are refused for the same reason.
• ◆Blank entries and duplicates are dropped, and the response shows the list as it was saved.