Customers

Create a customer

Creates a new, fully isolated proxy account. It starts with no bandwidth — give it some from your reseller pool with Allocate bandwidth.

POST /v1/customers
Content-Type: application/json

{ "label": "acme-inc" }

{
  "username": "bp_acmeinc_a1b2c3d4",
  "label": "acme-inc",
  "status": "active",
  "createdAt": "2026-08-22T10:00:00.000Z"
}

List customers

Pass ?status=active or ?status=suspended to filter.

GET /v1/customers

{
  "customers": [
    { "username": "bp_acmeinc_a1b2c3d4", "label": "acme-inc", "status": "active", "createdAt": "2026-08-22T10:00:00.000Z" }
  ]
}

Get a customer

Includes every active plan on the account — each plan's id is what you pass to Generate a proxy below.

GET /v1/customers/{username}

{
  "username": "bp_acmeinc_a1b2c3d4",
  "label": "acme-inc",
  "status": "active",
  "createdAt": "2026-08-22T10:00:00.000Z",
  "plans": [
    {
      "id": "plan_9f2a...",
      "productId": "residential-premium",
      "productKey": "premium",
      "remainingGb": 12.4,
      "dataGbRemaining": 12.4,
      "dataGbTotal": 20,
      "expiresAt": null,
      "generate": {
        "maxCount": 1000,
        "maxStickyMinutes": 60,
        "protocols": ["http", "socks5"],
        "targeting": { "country": true, "state": true, "city": true, "isp": false }
      }
    }
  ],
  "pending": []
}

generate tells you which options that plan's generate call accepts. pending lists GB you've allocated that is still being added to a plan — it moves onto plans within a few seconds.

Update a customer

Rename a customer with label, or suspend/reactivate it with status. A suspended customer can't generate new proxy lines; lines generated before the suspension may keep working until they rotate, so stop handing them out at the same time.

PATCH /v1/customers/{username}
Content-Type: application/json

{ "status": "suspended" }

{
  "username": "bp_acmeinc_a1b2c3d4",
  "label": "acme-inc",
  "status": "suspended",
  "createdAt": "2026-08-22T10:00:00.000Z"
}

Allocate bandwidth

Moves whole GB of one product from your reseller pool onto the customer. The first allocation of a product creates that plan on the customer; later ones add to it. Send an Idempotency-Key header so a retried request never moves the GB twice — a repeat returns alreadyApplied: true.

POST /v1/customers/{username}/allocate
Content-Type: application/json
Idempotency-Key: order-1042

{ "productKey": "premium", "gb": 10 }

{
  "productKey": "premium",
  "productId": "residential-premium",
  "gb": 10,
  "alreadyApplied": false,
  "poolRemainingGb": 40
}

Returns 402 if your pool holds less than gbof that product. Allocated bandwidth can't be moved back to your pool.

Generate a proxy

Issues a fresh, on-demand connection string against one of the customer's plans. Lines aren't persistent — call this whenever your integration needs a proxy, don't cache or store the result.

POST /v1/customers/{username}/generate
Content-Type: application/json

{
  "planId": "plan_9f2a...",
  "protocol": "http",
  "country": "US",
  "state": "California",
  "city": "Los Angeles",
  "stickyMinutes": 10
}

{
  "lines": ["acme_a1b2-country-us:xyz789@gw.buyproxy.org:6969"]
}

country, state, city, and isp are all optional — omit any of them for a worldwide, rotating IP. country takes a two-letter ISO code (US, DE). Set stickyMinutesto keep the same IP for up to the plan's generate.maxStickyMinutes; omit it for a fresh IP on every request. Suspended customers get 403.