HProxy Products & pricing API

openapi: 3.2.0
info:
  title: HProxy Products & pricing API
  version: 1.0.0
  description: 'Buy and manage proxies from a prepaid wallet, run the Scraper API, or use the free no-key APIs: a live proxy list, a proxy checker and an IP lookup. JSON in, JSON out. Money is always integer cents (120 = $1.20), never floats.'
  contact:
    url: https://hproxy.com/contact
  license:
    name: Proprietary
servers:
- url: https://hproxy.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Products & pricing
paths:
  /api/v1/products:
    get:
      operationId: products
      summary: List products
      description: 'The buyable catalog: for each product its family, its shape (what buying and delivery look like), its unit, description and features, its lifecycle, its published price, its quantity bounds and a how-to with the exact calls for that shape.'
      tags:
      - Products & pricing
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
  /api/v1/products/{id}:
    get:
      operationId: product-get
      summary: Read one product
      description: 'One product by its id, or by any id it used to carry, with its lifecycle. A retired product answers `200` with `state: "retired"` and `successorId`, never a `404`, so a menu built from an old catalog can tell its customer what to buy now. `state` is `active`, `parked` (listed, orders answer `409 product_unavailable` until it is back) or `retired`. `family` names the umbrella (`residential`, `isp`, `mobile`, `ipv4`, `ipv6`) so a storefront groups products without guessing from the name. `shape` says what buying and delivery look like, and it is what to key an integration on, never a list of ids: `gateway_gb` and `gateway_time` are a plan you generate lines from (`delivery` is `lines`), `addresses` and `addresses_mobile` are dedicated IPs that land in proxies (`delivery` is `addresses`). `renewal` is `topup` (order again, the units land on the plan you hold), `repurchase` (a fresh plan for a fresh period) or `extend` (an extension naming the addresses to keep). `howTo` spells the exact calls for that shape, from the price to the first use, with the targeting fields its network takes. A product we add on a known shape works in your code the day it lands.'
      tags:
      - Products & pricing
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                id: residential-lite
                name: Residential Lite
                family: residential
                state: active
                successorId: null
                available: true
                shape: gateway_gb
                unit: GB
                delivery: lines
                renewal: topup
                minQuantity: 1
                maxQuantity: 10000
                billing:
                  payg: true
                  subscription: true
                  intervals:
                  - month
                  - year
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
  /api/v1/products/{id}/price:
    get:
      operationId: price
      summary: Price a product
      description: 'A server-authoritative quote: the exact amount `POST /orders` will charge for the same inputs. Pass the quantity as a query parameter. For dedicated per-IP products, add `country` and `period_days` to quote the exact targeting you''ll order. Omitted, they default to `USA` / 30 days.


        **On a reseller key** the answer also says what the order costs **you**: `yourCostCents` is what we debit from your balance when one of your customers places it, `amountCents` is what that customer pays (your retail or markup, else our price), `marginCents` is the difference, `listCents` is our own price, and `note` spells out which is which. To see every period of a country at once, use the price list.'
      tags:
      - Products & pricing
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: quantity
        in: query
        required: true
        description: GB for residential, or number of IPs for dedicated products.
        schema:
          type: integer
      - name: country
        in: query
        required: false
        description: 'Per-IP products: target country, alpha-3 (e.g. USA, DEU). Default USA.'
        schema:
          type: string
      - name: period_days
        in: query
        required: false
        description: 'Per-IP products: rental period in days (e.g. 30, 90). Default 30.'
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                productId: residential-lite
                quantity: 5
                unitPriceCents: 100
                amountCents: 500
                currency: USD
                billingType: PAYG
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
  /api/v1/products/{id}/price-list:
    get:
      operationId: price-list
      summary: Price list for a country
      description: 'For **dedicated per-IP products** (ISP, IPv4, IPv6 and mobile IPs): every rental period of one country priced in one call, so you can print a price table without one quote per period. Each line carries `listCents`, our price for the order, and `available` (false when that period is sold out right now). Mobile answers one line per carrier, service and rotation mode for one period instead (pick it with `period_days`; the carrier ids go straight into `fulfillment_meta`), from the day''s price refresh, so quote one mobile order with price for the exact figure.


        **On a reseller key every line also says what it costs you**: `yourCostCents` is what we debit from your balance when one of your customers orders that line, `customerCents` what that customer pays (our price times your markup), and `marginCents` what you keep; `partner` states your discount, your markup and whether the product is on your catalog. The same table is under Pricing in your business dashboard. Products sold per GB or per speed tier answer `400 no_price_list`: they have one price per unit, which price quotes.'
      tags:
      - Products & pricing
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: country
        in: query
        required: true
        description: Alpha-3 from [options](#options), e.g. USA.
        schema:
          type: string
      - name: quantity
        in: query
        required: false
        description: 'How many IPs every line prices. Default: the product''s smallest order (1, or 10 for IPv6). A bigger order can cost less per IP.'
        schema:
          type: integer
      - name: period_days
        in: query
        required: false
        description: 'Mobile only: the period every carrier is priced for. Default 30.'
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                productId: isp
                unit: IP
                country: USA
                quantity: 1
                currency: USD
                countries:
                - alpha3: USA
                  name: United States
                - alpha3: TUR
                  name: Turkey
                partner:
                  discountPct: 20
                  markup: 1.3
                  sellable: true
                lines:
                - days: 7
                  period: 1 week
                  available: true
                  listCents: 250
                  yourCostCents: 200
                  customerCents: 325
                  marginCents: 125
                - days: 30
                  period: 1 month
                  available: true
                  listCents: 270
                  yourCostCents: 216
                  customerCents: 351
                  marginCents: 135
                note: listCents is our own price for this order. yourCostCents is what we debit from your balance when one of your customers orders it …
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
  /api/v1/products/{id}/options:
    get:
      operationId: options
      summary: Available countries & periods
      description: 'For **dedicated per-IP products** (IPv4, IPv6, ISP), the live list of countries you can order and the rental periods available, so you can build a picker without hardcoding anything. Countries come back as `{ name, alpha3 }` and are **kept current for you**: the list is refreshed from stock and a country that has run out is removed automatically, so what this returns is always orderable. Feed an `alpha3` straight into the `country` of price and orders, and a `days` into `period_days`. Gateway products (`delivery` is `lines`: residential, mobile, ISP rotating, IPv4 and IPv6 per GB) have no per-country configurator and return `400 no_options`: they target by country at generation time instead (see generate).'
      tags:
      - Products & pricing
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                productId: ipv4
                unit: IP
                minQuantity: 1
                maxQuantity: 1000
                countries:
                - name: United States
                  alpha3: USA
                - name: Germany
                  alpha3: DEU
                - name: United Kingdom
                  alpha3: GBR
                periods:
                - days: 30
                  label: 30 days
                - days: 90
                  label: 90 days
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your API key. Free keyless endpoints ignore it.
x-endpoint-count: 163
x-generated-from: https://hproxy.com/docs
x-llms: https://hproxy.com/llms-full.txt