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.

On a reseller key the answer also says what the order costs you: yourCostCents is what we debit from your balance when one of your customers places it, amountCents is what that customer pays (your retail or markup, else our price), marginCents is the difference, listCents is our own price, and note spells out which is which. To see every period of a country at once, use the price list.

For dedicated per-IP products (ISP, IPv4, IPv6 and mobile IPs): every rental period of one country priced in one call, so you can print a price table without one quote per period. Each line carries listCents, our price for the order, and available (false when that period is sold out right now). Mobile answers one line per carrier, service and rotation mode for one period instead (pick it with period_days; the carrier ids go straight into fulfillment_meta), from the day's price refresh, so quote one mobile order with price for the exact figure.

On a reseller key every line also says what it costs you: yourCostCents is what we debit from your balance when one of your customers orders that line, customerCents what that customer pays (our price times your markup), and marginCents what you keep; partner states your discount, your markup and whether the product is on your catalog. The same table is under Pricing in your business dashboard. Products sold per GB or per speed tier answer 400 no_price_list: they have one price per unit, which price quotes.

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).