Orders

Place an order

Request body

Request example Try it in the Dashboard

curl -X POST "https://papaproxy.net/account_new/api/v1/billing/composite/order" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"segments": [{"country": "US", "count": 100}], "period_months": 1, "whitelist_ips": ["203.0.113.10"], "use_balance": true, "idempotency_key": "order-2026-001"}'

import os

import requests

resp = requests.post(
    "https://papaproxy.net/account_new/api/v1/billing/composite/order",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    json={
        "segments": [
            {
                "country": "US",
                "count": 100
            }
        ],
        "period_months": 1,
        "whitelist_ips": [
            "203.0.113.10"
        ],
        "use_balance": True,
        "idempotency_key": "order-2026-001"
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://papaproxy.net/account_new/api/v1/billing/composite/order", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "segments": [
      {
        "country": "US",
        "count": 100
      }
    ],
    "period_months": 1,
    "whitelist_ips": [
      "203.0.113.10"
    ],
    "use_balance": true,
    "idempotency_key": "order-2026-001"
  }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/billing/composite/order');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'segments' => [[
            'country' => 'US',
            'count' => 100
        ]],
        'period_months' => 1,
        'whitelist_ips' => ['203.0.113.10'],
        'use_balance' => true,
        'idempotency_key' => 'order-2026-001'
    ]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	req, err := http.NewRequest("POST", "https://papaproxy.net/account_new/api/v1/billing/composite/order", strings.NewReader(`{"segments": [{"country": "US", "count": 100}], "period_months": 1, "whitelist_ips": ["203.0.113.10"], "use_balance": true, "idempotency_key": "order-2026-001"}`))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

• 201 The order was created. Check payment_required and amount_due_cents. · 27 fields

  Example response · JSONCopy

  {
    "service_id": "dea53a24-1760-501d-a60a-d438bd176599",
    "status": "pending",
    "segments": [
      {
        "country": 197148,
        "country_code": "US",
        "count": 100,
        "unit_base_cents": 19,
        "type_multiplier": 1.0,
        "geo_multiplier": 1.0,
        "segment_price_cents": 1900,
        "available": true
      }
    ],
    "total_ip": 100,
    "total_price_cents": 1900,
    "period_months": 1,
    "discount_pct": 0,
    "monthly_price_cents": 1900,
    "balance_applied_cents": 1777,
    "amount_due_cents": 123,
    "invoice_url": null,
    "payment_required": true,
    "intent_id": "2dbb7b45-5fb8-5bc9-834f-32aeaa569d72",
    "promo_code_applied": null,
    "promo_discount_cents": 0,
    "total_before_promo_cents": null,
    "trial": false,
    "trial_period_days": null,
    "addon_monthly_cents": 0
  }

  Field	Type	Description
  service_id required	string (uuid)	Created service ID
  status required	string	active when the order is paid, pending while amount_due_cents is unpaid.
  segments	array of object	Per-segment breakdown as ordered
  segments[].country required	integer	Numeric country ID. The ISO code is in country_code.
  segments[].country_code	string, nullable	ISO 3166-1 alpha-2 country code (e.g. "DE").
  segments[].count required	integer
  segments[].unit_base_cents required	integer	Volume-tier base unit price in integer cents per IP
  segments[].type_multiplier required	number	Product multiplier applied to the base rate.
  segments[].geo_multiplier required	number	Country multiplier (default 1.0).
  segments[].segment_price_cents required	integer	Segment price: count × base rate × product multiplier × country multiplier, rounded up to whole cents.
  segments[].available required	boolean	Whether enough IPs are available for this segment.
  total_ip required	integer	Total number of IPs.
  total_price_cents required	integer	Discounted total charged for the full period in integer cents
  period_months	integer	Billing period length in months (1/3/6/12)Default: 1
  discount_pct	integer	Applied period discount as a whole percentage (0/10/15/20)Default: 0
  monthly_price_cents	integer	Undiscounted monthly total (sum of segment prices) in integer centsDefault: 0
  balance_applied_cents	integer	Amount paid from your wallet balance, in cents. Zero when use_balance is false.Default: 0
  amount_due_cents	integer	Amount still due through a payment processor, in cents. Zero when the balance covers the order.Default: 0
  invoice_url	string, nullable	Link to the invoice, if one was issued.
  payment_required	boolean	true when amount_due_cents must still be paid. Pay it in the Dashboard under Pending payments.Default: false
  intent_id	string (uuid), nullable	ID of the pending payment when payment_required is true.
  promo_code_applied	string, nullable	Promo code applied to the order, if any.
  promo_discount_cents	integer	Promo discount applied to the order, in cents.Minimum: 0Default: 0
  total_before_promo_cents	integer, nullable	Pre-promo total when a promo was applied; null otherwise.
  trial	boolean	True when the service is a paid trial.Default: false
  trial_period_days	integer, nullable	Trial length in days; null for regular orders.
  addon_monthly_cents	integer	Monthly cost of add-ons bought with the order, in cents.Minimum: 0Default: 0

• 401 The API key is missing, malformed, revoked, or expired, or the account is inactive.

  Example · JSONCopy

  {
    "detail": "Invalid or revoked API key."
  }

  Error format

• 403 The API key lacks scope services:write.

  Example · JSONCopy

  {
    "detail": "API key is missing required scope: services:write"
  }

  Error format

• 422 Validation error, fewer than 100 IPs in total, or no whitelisted IP.

  Example · JSONCopy

  {
    "detail": {
      "error": "WHITELIST_REQUIRED",
      "message": "A proxy service requires at least one whitelisted IP at order time. …"
    }
  }

  Error format

• 429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.

  Example · JSONCopy

  {
    "detail": "Too Many Requests"
  }

  Error format

Quote additional IPs

Parameters

Request body

Request example Try it in the Dashboard

curl -X POST "https://papaproxy.net/account_new/api/v1/billing/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/add-ips/quote" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"segments": [{"country": "US", "count": 100}]}'

import os

import requests

resp = requests.post(
    "https://papaproxy.net/account_new/api/v1/billing/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/add-ips/quote",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    json={
        "segments": [
            {
                "country": "US",
                "count": 100
            }
        ]
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://papaproxy.net/account_new/api/v1/billing/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/add-ips/quote", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "segments": [
      {
        "country": "US",
        "count": 100
      }
    ]
  }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/billing/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/add-ips/quote');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'segments' => [[
            'country' => 'US',
            'count' => 100
        ]]
    ]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	req, err := http.NewRequest("POST", "https://papaproxy.net/account_new/api/v1/billing/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/add-ips/quote", strings.NewReader(`{"segments": [{"country": "US", "count": 100}]}`))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

• 200 Non-binding preview of an add-ips top-up. · 20 fields

  Example response · JSONCopy

  {
    "service_id": "cb532178-5b03-506a-84ea-0230ff28576b",
    "segments": [
      {
        "country": 197148,
        "country_code": "US",
        "count": 100,
        "unit_base_cents": 19,
        "type_multiplier": 1.0,
        "geo_multiplier": 1.0,
        "segment_price_cents": 1900,
        "available": true
      }
    ],
    "errors": [],
    "added_ip_count": 100,
    "monthly_price_added_cents": 1900,
    "days_remaining": 60,
    "days_per_month": 30,
    "prorated_charge_cents": 3798,
    "current_price_cents": 9500,
    "new_renewal_price_cents": 11400
  }

  Field	Type	Description
  service_id required	string (uuid)	ID of the service.
  segments	array of object	Per-segment pricing breakdown for the added IPs
  segments[].country required	integer	Numeric country ID. The ISO code is in country_code.
  segments[].country_code	string, nullable	ISO 3166-1 alpha-2 country code (e.g. "DE").
  segments[].count required	integer
  segments[].unit_base_cents required	integer	Volume-tier base unit price in integer cents per IP
  segments[].type_multiplier required	number	Product multiplier applied to the base rate.
  segments[].geo_multiplier required	number	Country multiplier (default 1.0).
  segments[].segment_price_cents required	integer	Segment price: count × base rate × product multiplier × country multiplier, rounded up to whole cents.
  segments[].available required	boolean	Whether enough IPs are available for this segment.
  errors	array of object	Segments that can't be fulfilled; ordering them would fail with HTTP 409.
  errors[].country required	integer	Numeric country ID of the segment that was left out.
  errors[].message required	string
  added_ip_count required	integer	Total IPs across the added segments
  monthly_price_added_cents required	integer	Undiscounted full-monthly cost of the added segments
  days_remaining required	integer	Days left in the current term.
  days_per_month	integer	Days per month used for proration.Default: 30
  prorated_charge_cents required	integer	Amount charged now for the remainder of the current period
  current_price_cents required	integer	Service's current full-period renewal price
  new_renewal_price_cents required	integer	Renewal price after this top-up (current + added segments' full-period cost)

• 401 The API key is missing, malformed, revoked, or expired, or the account is inactive.

  Example · JSONCopy

  {
    "detail": "Invalid or revoked API key."
  }

  Error format

• 404 Service not found, or it doesn't belong to your account.

  Example · JSONCopy

  {
    "detail": "Service 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found."
  }

  Error format

• 422 Validation error, or fewer than 100 IPs in a proxy-package request.

  Example · JSONCopy

  {
    "detail": "Validation error"
  }

  Error format

• 429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.

  Example · JSONCopy

  {
    "detail": "Too Many Requests"
  }

  Error format

Add IPs to a service

Parameters

Request body

Request example Try it in the Dashboard

curl -X POST "https://papaproxy.net/account_new/api/v1/billing/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/add-ips" \
  -H "Authorization: Bearer $PAPAPROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"segments": [{"country": "US", "count": 100}], "idempotency_key": "add-ips-2026-001"}'

import os

import requests

resp = requests.post(
    "https://papaproxy.net/account_new/api/v1/billing/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/add-ips",
    headers={"Authorization": f"Bearer {os.environ['PAPAPROXY_API_KEY']}"},
    json={
        "segments": [
            {
                "country": "US",
                "count": 100
            }
        ],
        "idempotency_key": "add-ips-2026-001"
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://papaproxy.net/account_new/api/v1/billing/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/add-ips", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAPAPROXY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "segments": [
      {
        "country": "US",
        "count": 100
      }
    ],
    "idempotency_key": "add-ips-2026-001"
  }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

<?php
$ch = curl_init('https://papaproxy.net/account_new/api/v1/billing/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/add-ips');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAPAPROXY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'segments' => [[
            'country' => 'US',
            'count' => 100
        ]],
        'idempotency_key' => 'add-ips-2026-001'
    ]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
var_dump($status, json_decode($response, true));

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	req, err := http.NewRequest("POST", "https://papaproxy.net/account_new/api/v1/billing/services/3fa85f64-5717-4562-b3fc-2c963f66afa6/add-ips", strings.NewReader(`{"segments": [{"country": "US", "count": 100}], "idempotency_key": "add-ips-2026-001"}`))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PAPAPROXY_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}

Responses

• 200 Result of a successful add-ips top-up. · 7 fields

  Example response · JSONCopy

  {
    "service_id": "cb532178-5b03-506a-84ea-0230ff28576b",
    "added_ip_count": 100,
    "charged_cents": 3799,
    "ledger_entry_id": "18e0387a-1131-5ccd-a3f7-2d406d4cf5b3",
    "new_total_ip": 500,
    "new_price_cents": 9500,
    "segments": [
      {
        "count": 500,
        "country": 197148
      }
    ]
  }

  Field	Type	Description
  service_id required	string (uuid)	ID of the service.
  added_ip_count required	integer	Number of IPs added.
  charged_cents required	integer	Prorated amount charged to the wallet
  ledger_entry_id	string (uuid), nullable	Wallet transaction for the charge; null when nothing was charged.
  new_total_ip required	integer	Total IP count on the service after the top-up
  new_price_cents required	integer	Service's new full-period renewal price
  segments	array of object	All segments of the service after the top-up.

• 401 The API key is missing, malformed, revoked, or expired, or the account is inactive.

  Example · JSONCopy

  {
    "detail": "Invalid or revoked API key."
  }

  Error format

• 402 Insufficient wallet balance. Nothing is charged.

  Example · JSONCopy

  {
    "detail": {
      "detail": "insufficient_funds",
      "required_cents": 3799,
      "balance_cents": 1777,
      "deficit_cents": 2022
    }
  }

  Error format

• 403 The API key lacks scope services:write.

  Example · JSONCopy

  {
    "detail": "API key is missing required scope: services:write"
  }

  Error format

• 404 Service not found, or it doesn't belong to your account.

  Example · JSONCopy

  {
    "detail": "Service 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found."
  }

  Error format

• 422 Validation error (for example, a missing idempotency_key), or fewer than 100 IPs in a proxy-package request.

  Example · JSONCopy

  {
    "detail": "Validation error"
  }

  Error format

• 429 Too many requests: the per-account limit is 60 requests per minute, shared by all keys and the MCP server. Retry with exponential backoff.

  Example · JSONCopy

  {
    "detail": "Too Many Requests"
  }

  Error format