HProxy Orders API

openapi: 3.2.0
info:
  title: HProxy Orders 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: Orders
paths:
  /api/v1/orders:
    post:
      operationId: orders-create
      summary: Create an order
      description: 'Buy a product. By default this is a wallet prepay: it debits your balance and returns immediately, or fails with `402` if the balance is short (it never silently charges a card you didn''t pick). Set `method` to `"card"` or `"crypto"` to get a hosted `payUrl` back instead. Always send an `Idempotency-Key` so a retry never double-charges; on a reseller key an order without one is refused.


        The body takes **only the five fields below**. Anything else, including a top-level `country`, is refused with `400 unknown_field` before anything is charged. What goes in it depends on the product''s `delivery` on GET /products.


        **Residential and other gateway products** (`delivery` is `lines`): send `product_id` and `quantity`, nothing else. There is no country in the order. You choose the country for each line when you generate lines from the plan, so one plan serves every country. A package size is the `quantity` (1 GB is `1`, 10 GB is `10`), never a separate product id, and it is a whole number from the product''s `minQuantity`.


        **Dedicated IPs** (`delivery` is `addresses`: IPv4, IPv6, ISP and mobile IPs): `quantity` counts IPs, and the targeting goes inside `fulfillment_meta`, for example `{"country": "DEU", "period_days": 30}`.'
      tags:
      - Orders
      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: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                product_id:
                  type: string
                  description: A product id from GET /products, e.g. "residential-lite".
                quantity:
                  type: integer
                  description: 'A whole number; a fraction is refused. GB for residential and other per-GB products, or number of IPs for dedicated products, between the product''s `minQuantity` and `maxQuantity`. For renewals: the number of ids.'
                method:
                  type: string
                  description: '"wallet" (default), "card" or "crypto". card/crypto return a payUrl.'
                fulfillment_meta:
                  type: object
                  description: 'Dedicated IPs: country (alpha-3, e.g. "DEU"), period_days, and operator_id on mobile. For a RENEWAL of dedicated proxies: {"kind": "extension", "ids": ["…"], "period_days": 30} (ids from GET /proxies, ownership-checked server-side). Leave it out for residential and other per-GB products: you choose their country per line at POST /plans/{id}/generate.'
                expected_amount_cents:
                  type: integer
                  description: The total you showed the buyer (the `amountCents` of your quote). If the price moved in between, the order is refused with `409 price_changed` carrying the new `amountCents`, and nothing is charged. Omit it to be charged the price at the moment of the order.
              required:
              - product_id
              - quantity
    get:
      operationId: orders-list
      summary: List orders
      description: Your order history, newest first, one page at a time. Without parameters you get the 15 most recent.
      tags:
      - Orders
      parameters:
      - name: limit
        in: query
        required: false
        description: Page size, 1 to 200. Default 15. A larger value is capped at 200.
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Rows to skip, newest first. Default 0. Page 3 of 50 is `limit=50&offset=100`.
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                orders:
                - orderId: ord_8f491789-58cd-4e82-81a2-ec7c28088821
                  productId: residential-lite
                  type: PURCHASE
                  status: PAYMENT_RECEIVED
                  quantityGb: 1
                  amountCents: 120
                  currency: USD
                  createdAt: '2026-07-11T09:46:05.191+00:00'
        '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/orders/{id}:
    get:
      operationId: orders-get
      summary: Get an order
      description: Fetch a single order by its id to poll fulfillment status. Once it reads `completed`, a dedicated-IP order's proxies are ready at GET /proxies?order_id=….
      tags:
      - Orders
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      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: []
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