API ordering

Place a wallet-paid order

Place a headless, wallet-paid order. The server forces pay_with_credit=1 and no_redirect=1 internally, so the order is debited from your wallet balance with no gateway redirect.

email, fname, and lname are derived from the authenticated identity. You can omit them, or pass them explicitly to override.

Permission: account:api_ordering:write (admin-grant-only — off by default for every account). Authenticate with the api-token header. The wallet balance must cover the order total at the moment the call lands.

POST

account

orders

create

curl --request POST \
  --url https://api.proxyscrape.com/v4/account/orders/create \
  --header 'Content-Type: application/json' \
  --header 'api-token: <api-key>' \
  --data '
{
  "type": "new_datacenter_shared"
}
'

{
  "success": true,
  "data": "0bc1a40f-2a17-4c84-9b2b-f4b9d3e0b3a1"
}

{
  "success": false,
  "error": "account_id is required for update_* order types. To create a new subaccount, use the matching new_* type."
}

{
  "success": false,
  "error": "Could not determine account email from authenticated identity."
}

{
  "success": false,
  "error": "The account_id does not belong to the authenticated account."
}

Authorizations

api-token

string

header

required

API key. Create and manage keys at /v4/account/api-keys or in the dashboard.

Body

application/json

type

enum<string>

required

Product to order. new_* creates a new subaccount; update_* upgrades an existing one in place (more proxies/tokens/bandwidth or extended duration) and requires account_id. Each update_* accepts the same product-specific fields as its matching new_* — see the examples below.

Available options:

new_datacenter_shared,

new_residential,

new_residential_unlimited,

new_serp_api,

update_datacenter_shared,

update_datacenter_dedicated,

update_residential,

update_residential_unlimited,

update_serp_api

account_id

string

Required for update_* types: the AccountID of the subaccount to upgrade (from /v4/account/subaccounts). Must be a subaccount you own. Ignored for new_* types.

Example:

"fe7941e6-1eed-4d95-881a-3159901897d3"

dry_run

boolean

When true, returns a price quote without creating an order or debiting the wallet. Works for both new_* and update_*, and on a zero wallet balance.

Example:

false

country

string

Billing country (full name, e.g. "Belgium"). Determines VAT. Required for new_* orders; optional for update_* (the subaccount's existing country is used).

Example:

"Belgium"

coupon_code

string

Optional coupon. Discount applies before any per-account API-ordering percentage (coupon first, then percentage on the post-coupon price). Coupons cannot be applied to wallet top-ups.

Example:

"WELCOME10"

fname

string

Override the first name from the authenticated account.

lname

string

Override the last name from the authenticated account.

Response

For a real order: created and paid from the wallet — data is the bare order ID string. For dry_run: true: data is a price quote and no order is created or charged.

success

boolean

Example:

true

data

Order ID (returned for wallet-credit orders).

Example:

"0bc1a40f-2a17-4c84-9b2b-f4b9d3e0b3a1"

Read order statusReturns the lifecycle state of a previously placed order. Consumers `POST /v4/account/orders/create`, then poll this endpoint every 1–2 seconds with the returned `order_id` until `status === "processed"`. At that point `data.subaccount` is populated with the same shape `/v4/account/subaccounts` emits, so the caller can drop it straight into per-product endpoints like `/v4/account/{AccountID}/datacenter_shared/proxy-list`. Gated on `account:api_ordering:read`. The order's email must match the authenticated identity — mismatches return 404 (not 403) so existence isn't leaked.

curl --request POST \
  --url https://api.proxyscrape.com/v4/account/orders/create \
  --header 'Content-Type: application/json' \
  --header 'api-token: <api-key>' \
  --data '
{
  "type": "new_datacenter_shared"
}
'

{
  "success": true,
  "data": "0bc1a40f-2a17-4c84-9b2b-f4b9d3e0b3a1"
}

{
  "success": false,
  "error": "account_id is required for update_* order types. To create a new subaccount, use the matching new_* type."
}

{
  "success": false,
  "error": "Could not determine account email from authenticated identity."
}

{
  "success": false,
  "error": "The account_id does not belong to the authenticated account."
}