Orders
POST /orders buys a product from your wallet (or returns a hosted payUrl for card and crypto). GET /orders lists history, GET /orders/{id} polls one.
hproxy.com/api/v1/orderskey# Residential: product_id + quantity (GB). No country here:
# the country is chosen per line at POST /plans/{id}/generate.
curl -X POST https://hproxy.com/api/v1/orders \
-H "X-API-Key: hpx_your_key_here" \
-H "Idempotency-Key: order-2026-07-11-001" \
-H "Content-Type: application/json" \
-d '{"product_id":"residential-lite","quantity":1}'Create an order
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}.
| Parameter | Type | Required | Description |
|---|---|---|---|
product_id | string | required | A product id from GET /products, e.g. "residential-lite". |
quantity | integer | required | 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 | string | optional | "wallet" (default), "card" or "crypto". card/crypto return a payUrl. |
fulfillment_meta | object | optional | 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 | integer | optional | 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. |
hproxy.com/api/v1/orderskeycurl "https://hproxy.com/api/v1/orders?limit=50&offset=0" -H "X-API-Key: hpx_your_key_here"List orders
Your order history, newest first, one page at a time. Without parameters you get the 15 most recent.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer (query) | optional | Page size, 1 to 200. Default 15. A larger value is capped at 200. |
offset | integer (query) | optional | Rows to skip, newest first. Default 0. Page 3 of 50 is limit=50&offset=100. |
hproxy.com/api/v1/orders/{id}keycurl https://hproxy.com/api/v1/orders/ord_8f49...8821 \
-H "X-API-Key: hpx_your_key_here"Get an order
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=….
order.fulfilled / order.failed / order.refunded the moment they happen.Need a hand wiring this up? Email support@hproxy.com. A real person reads every message.