API
Orders and purchases
A purchase takes two requests: the price first, then the purchase with an Idempotency-Key. A repeated purchase request with the same key returns the first order and charges nothing more.
Updated 22 November 2026
Prices and stock#
| Request | Returns |
|---|---|
| GET /pricing/me | The account's price list for every product and term. |
| GET /catalog/availability?proxy_type=isp | Locations a product can be bought in now: datacenter, isp, mtproto or residential. |
| GET /mobile/locations?in_stock=true | Mobile locations with carriers, prices and capabilities. The location's slug is its location_code. |
Step 1. The price#
POST /orders/quote returns what a new order costs today. Nothing is bought. It needs the read or purchase permission.
| Field | Value |
|---|---|
| proxy_type | datacenter, isp, residential, mobile or mtproto |
| location_code | Country code such as US, a city such as us_la, or a mobile location slug |
| proxy_count | 1 to 1000. Gigabytes for residential |
| duration_days | 1 to 365 |
| variant | Optional. web for a Telegram WEB proxy, pro for Residential Pro |
| features | Optional, mobile only. Required device capabilities |
The answer has unit_price (per proxy, per gigabyte for residential), total, balance and enough_balance. A promo code or the one-time referral discount can lower the amount charged, never raise it.
Step 2. The purchase#
POST /orders takes the same fields plus location_name (the name shown in the dashboard), unit_price from the quote and an optional promo_code. It needs the purchase permission.
PLAN='{"proxy_type":"datacenter","location_code":"US","proxy_count":2,"duration_days":30}'
# 1. The price. Nothing is bought.
PRICE=$(curl -s https://proxya.co/api/v1/orders/quote \
-H "Authorization: Bearer $PROXYA_API_KEY" \
-H "Content-Type: application/json" \
-d "$PLAN" | jq -r .unit_price)
# 2. The purchase. One key per purchase, the same key on every retry.
KEY=$(uuidgen)
curl https://proxya.co/api/v1/orders \
-H "Authorization: Bearer $PROXYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $KEY" \
--max-time 300 \
-d "$(echo "$PLAN" | jq --arg p "$PRICE" '. + {location_name: "United States", unit_price: $p}')"Idempotency-Key#
- A purchase, renewal or restore made with a key must carry an
Idempotency-Keyheader: 1 to 128 printable ASCII characters, a new value for each purchase. - For 24 hours a request with the same value and the same body returns the first answer: the same order or the same error. Nothing is charged twice.
- The same value with a different body answers
409. So does a repeat while the first request is still running. - A failed purchase is not repeated under the same value. Check the orders, then buy with a new value.
unit_price must match the current price. If prices change between the two steps the purchase answers 400. Request a new quote and buy again.
Orders#
curl "https://proxya.co/api/v1/orders?status=active&limit=50" \
-H "Authorization: Bearer $PROXYA_API_KEY"
curl https://proxya.co/api/v1/orders/$ORDER_ID \
-H "Authorization: Bearer $PROXYA_API_KEY"GET /orderstakesstatus,proxy_type,search,pageandlimitup to 100.GET /orders/{id}returns the order with its proxies andrenew_options.{id}is the orderidor itsorder_number.- Statuses:
pending,provisioning,active,expiring,suspended,terminated,expired,cancelled. An order inprovisioningis still being set up: read it again later. - Without the credentials permission the proxies come back with empty logins, passwords and links, and the order has
credentials_hidden: true.
Renewal#
renew_options in the order lists every term the order can be renewed for, each with today's price per proxy. POST /orders/{id}/extend takes duration_days and unit_price from that list and needs an Idempotency-Key.
import uuid
order = session.get(f"{API}/orders/{order_id}", timeout=30).json()
option = next(o for o in order["renew_options"] if o["duration_days"] == 30)
renewed = session.post(
f"{API}/orders/{order_id}/extend",
json={"duration_days": option["duration_days"], "unit_price": str(option["unit_price"])},
headers={"Idempotency-Key": str(uuid.uuid4())},
timeout=300,
)
renewed.raise_for_status()
print(renewed.json()["expires_at"])POST /orders/{id}/restore with the same body brings back a terminated ISP or datacenter order within 7 days after termination, with the same IPs and credentials. Rules for each product are on Orders and renewals.
Didn't find the answer?
Support answers in the chat on this site around the clock. On Telegram the reply usually comes fastest, and a ticket gets an answer by email.