Products & pricing

The buyable catalog: for each product its family, its shape (what buying and delivery look like), its unit, description and features, its lifecycle, its published price, its quantity bounds and a how-to with the exact calls for that shape.

One product by its id, or by any id it used to carry, with its lifecycle. A retired product answers 200 with state: "retired" and successorId, never a 404, so a menu built from an old catalog can tell its customer what to buy now. state is active, parked (listed, orders answer 409 product_unavailable until it is back) or retired. family names the umbrella (residential, isp, mobile, ipv4, ipv6) so a storefront groups products without guessing from the name. shape says what buying and delivery look like, and it is what to key an integration on, never a list of ids: gateway_gb and gateway_time are a plan you generate lines from (delivery is lines), addresses and addresses_mobile are dedicated IPs that land in proxies (delivery is addresses). renewal is topup (order again, the units land on the plan you hold), repurchase (a fresh plan for a fresh period) or extend (an extension naming the addresses to keep). howTo spells the exact calls for that shape, from the price to the first use, with the targeting fields its network takes. A product we add on a known shape works in your code the day it lands.

A server-authoritative quote: the exact amount POST /orders will charge for the same inputs. Pass the quantity as a query parameter. For dedicated per-IP products, add country and period_days to quote the exact targeting you'll order. Omitted, they default to USA / 30 days.

For dedicated per-IP products (IPv4, IPv6, ISP), the live list of countries you can order and the rental periods available, so you can build a picker without hardcoding anything. Countries come back as { name, alpha3 } and are kept current for you: the list is refreshed from stock and a country that has run out is removed automatically, so what this returns is always orderable. Feed an alpha3 straight into the country of price and orders, and a days into period_days. Gateway products (delivery is lines: residential, mobile, ISP rotating, IPv4 and IPv6 per GB) have no per-country configurator and return 400 no_options: they target by country at generation time instead (see generate).