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#

RequestReturns
GET /pricing/meThe account's price list for every product and term.
GET /catalog/availability?proxy_type=ispLocations a product can be bought in now: datacenter, isp, mtproto or residential.
GET /mobile/locations?in_stock=trueMobile 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.

FieldValue
proxy_typedatacenter, isp, residential, mobile or mtproto
location_codeCountry code such as US, a city such as us_la, or a mobile location slug
proxy_count1 to 1000. Gigabytes for residential
duration_days1 to 365
variantOptional. web for a Telegram WEB proxy, pro for Residential Pro
featuresOptional, 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-Key header: 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#

Shell
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 /orders takes status, proxy_type, search, page and limit up to 100.
  • GET /orders/{id} returns the order with its proxies and renew_options. {id} is the order id or its order_number.
  • Statuses: pending, provisioning, active, expiring, suspended, terminated, expired, cancelled. An order in provisioning is 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.