Endpoints on this page
GET /v1/catalog/products: Products, plans and pricesPOST /v1/orders: Buy a plan from the balance (new service or more traffic)GET /v1/orders: List ordersGET /v1/orders/{orderId}: Get an order
Base URL https://droidkeep.com/api/v1. Authentication, errors and limits: see the API overview.
Products, plans and prices
GET/v1/catalog/products
Every product with its plans and prices, exactly as charged when you order.
Public: no API key needed.
Response 200 OK
{
"data": [
{
"id": "residential",
"name": "NAME",
"description": "DESCRIPTION",
"unit": "GB",
"plans": [
{
"id": "res-10",
"productId": "residential",
"name": "Starter",
"quantity": 0,
"unit": "GB",
"durationDays": null,
"price": "29.00",
"pricePerUnit": "29.00",
"popular": false,
"features": [
"FEATURES"
],
"available": false,
"countries": [
"US"
]
}
]
}
]
}Code examples
curl -s "https://droidkeep.com/api/v1/catalog/products"import os
import requests
API = "https://droidkeep.com/api/v1"
r = requests.get(f"{API}/catalog/products", timeout=30)
r.raise_for_status()
print(r.json())// Node.js 18+ (built-in fetch), ES module
const API = 'https://droidkeep.com/api/v1';
const res = await fetch(`${API}/catalog/products`);
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());Buy a plan from the balance (new service or more traffic)
POST/v1/orders
Always paid from the prepaid balance: the price is computed by the API (catalogue price × quantity), the balance is debited, the service is created or extended and the order comes back completed with its fulfillment. The proxy credentials are available at once.
Balance too low → 402 insufficient_balance, with the missing amount and a suggested top-up in error.details (missing, suggestedTopUp). Nothing is debited on any error. To pay the difference, start a top-up carrying the same request in purchase (POST /v1/topups): the plan is bought as soon as the top-up is credited.
Authentication: API key in the Authorization: Bearer API_KEY header.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | No | Unique key (e.g. a UUID) to safely retry a POST. Kept 24 h. — max. 128 characters |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
planId | string | Yes | — |
quantity | integer | No | 1–100, default 1 |
options | object | No | — |
{
"planId": "PLAN_ID",
"quantity": 1,
"options": {
"country": "US",
"carrier": "CARRIER",
"city": "CITY",
"subscriptionId": "SUBSCRIPTION_ID",
"portId": "PORT_ID",
"autoRenew": false,
"domains": [
{
"name": "example.com",
"years": 1,
"privacy": false,
"action": "register",
"autoRenew": false,
"authCode": null,
"authCodeProvided": false,
"ownership": "self"
}
],
"registrant": {
"email": "EMAIL",
"name": "NAME",
"organization": "ORGANIZATION",
"country": "COUNTRY",
"address": {
"street": "STREET",
"city": "CITY",
"state": "STATE",
"postalCode": "POSTAL_CODE"
},
"phone": "PHONE",
"eligibility": [
{
"tld": "eu",
"country": "COUNTRY",
"nexusCategory": "C11",
"purpose": "P1"
}
]
},
"nameservers": {
"mode": "default"
},
"agreements": {
"terms": true,
"registrantBenefits": true,
"acceptedAt": "2026-10-05T14:03:11Z",
"termsUrl": null
},
"esim": [
{
"planId": "PLAN_ID",
"code": "CODE",
"qty": 1
}
],
"esimTopup": {
"iccid": "ICCID",
"planId": "PLAN_ID"
}
}
}Response 201 Created
{
"id": "ord_4f8k2m9q",
"status": "completed",
"productId": "residential",
"planId": "PLAN_ID",
"planName": "PLAN_NAME",
"quantity": 0,
"unitPrice": "29.00",
"subtotal": "29.00",
"discount": "29.00",
"total": "29.00",
"promoCode": null,
"currency": "USD",
"topUpId": null,
"options": {
"country": "US",
"carrier": "CARRIER",
"city": "CITY",
"subscriptionId": "SUBSCRIPTION_ID",
"portId": "PORT_ID",
"autoRenew": false,
"domains": [
{
"name": "example.com",
"years": 1,
"privacy": false,
"action": "register",
"autoRenew": false,
"authCode": null,
"authCodeProvided": false,
"ownership": "self"
}
],
"registrant": {
"email": "EMAIL",
"name": "NAME",
"organization": "ORGANIZATION",
"country": "COUNTRY",
"address": {
"street": "STREET",
"city": "CITY",
"state": "STATE",
"postalCode": "POSTAL_CODE"
},
"phone": "PHONE",
"eligibility": [
{
"tld": "eu",
"country": "COUNTRY",
"nexusCategory": "C11",
"purpose": "P1"
}
]
},
"nameservers": {
"mode": "default"
},
"agreements": {
"terms": true,
"registrantBenefits": true,
"acceptedAt": "2026-10-05T14:03:11Z",
"termsUrl": null
},
"esim": [
{
"planId": "PLAN_ID",
"code": "CODE",
"qty": 1
}
],
"esimTopup": {
"iccid": "ICCID",
"planId": "PLAN_ID"
}
},
"fulfillment": null,
"createdAt": "2026-10-05T14:03:11Z",
"paidAt": "2026-10-05T14:03:11Z"
}Code examples
curl -s -X POST "https://droidkeep.com/api/v1/orders" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"planId":"PLAN_ID","quantity":1,"options":{"country":"US","carrier":"CARRIER","city":"CITY","subscriptionId":"SUBSCRIPTION_ID","portId":"PORT_ID","autoRenew":false,"domains":[{"name":"example.com","years":1,"privacy":false,"action":"register","autoRenew":false,"authCode":null,"authCodeProvided":false,"ownership":"self"}],"registrant":{"email":"EMAIL","name":"NAME","organization":"ORGANIZATION","country":"COUNTRY","address":{"street":"STREET","city":"CITY","state":"STATE","postalCode":"POSTAL_CODE"},"phone":"PHONE","eligibility":[{"tld":"eu","country":"COUNTRY","nexusCategory":"C11","purpose":"P1"}]},"nameservers":{"mode":"default"},"agreements":{"terms":true,"registrantBenefits":true,"acceptedAt":"2026-10-05T14:03:11Z","termsUrl":null},"esim":[{"planId":"PLAN_ID","code":"CODE","qty":1}],"esimTopup":{"iccid":"ICCID","planId":"PLAN_ID"}}}'import os, uuid
import requests
API = "https://droidkeep.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}
r = requests.post(f"{API}/orders", headers=HEADERS, json={
"planId": "PLAN_ID",
"quantity": 1,
"options": {
"country": "US",
"carrier": "CARRIER",
"city": "CITY",
"subscriptionId": "SUBSCRIPTION_ID",
"portId": "PORT_ID",
"autoRenew": False,
"domains": [{
"name": "example.com",
"years": 1,
"privacy": False,
"action": "register",
"autoRenew": False,
"authCode": None,
"authCodeProvided": False,
"ownership": "self",
}],
"registrant": {
"email": "EMAIL",
"name": "NAME",
"organization": "ORGANIZATION",
"country": "COUNTRY",
"address": {
"street": "STREET",
"city": "CITY",
"state": "STATE",
"postalCode": "POSTAL_CODE",
},
"phone": "PHONE",
"eligibility": [{
"tld": "eu",
"country": "COUNTRY",
"nexusCategory": "C11",
"purpose": "P1",
}],
},
"nameservers": {"mode": "default"},
"agreements": {
"terms": True,
"registrantBenefits": True,
"acceptedAt": "2026-10-05T14:03:11Z",
"termsUrl": None,
},
"esim": [{"planId": "PLAN_ID", "code": "CODE", "qty": 1}],
"esimTopup": {"iccid": "ICCID", "planId": "PLAN_ID"},
},
}, timeout=30)
r.raise_for_status()
print(r.json())// Node.js 18+ (built-in fetch), ES module
import { randomUUID } from 'node:crypto';
const API = 'https://droidkeep.com/api/v1';
const res = await fetch(`${API}/orders`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Idempotency-Key': randomUUID(), 'Content-Type': 'application/json' },
body: JSON.stringify({
planId: 'PLAN_ID',
quantity: 1,
options: {
country: 'US',
carrier: 'CARRIER',
city: 'CITY',
subscriptionId: 'SUBSCRIPTION_ID',
portId: 'PORT_ID',
autoRenew: false,
domains: [{
name: 'example.com',
years: 1,
privacy: false,
action: 'register',
autoRenew: false,
authCode: null,
authCodeProvided: false,
ownership: 'self',
}],
registrant: {
email: 'EMAIL',
name: 'NAME',
organization: 'ORGANIZATION',
country: 'COUNTRY',
address: {
street: 'STREET',
city: 'CITY',
state: 'STATE',
postalCode: 'POSTAL_CODE',
},
phone: 'PHONE',
eligibility: [{
tld: 'eu',
country: 'COUNTRY',
nexusCategory: 'C11',
purpose: 'P1',
}],
},
nameservers: { mode: 'default' },
agreements: {
terms: true,
registrantBenefits: true,
acceptedAt: '2026-10-05T14:03:11Z',
termsUrl: null,
},
esim: [{ planId: 'PLAN_ID', code: 'CODE', qty: 1 }],
esimTopup: { iccid: 'ICCID', planId: 'PLAN_ID' },
},
}),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());List orders
GET/v1/orders
Authentication: API key in the Authorization: Bearer API_KEY header.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
page | query | integer | No | ≥ 1, default 1 |
perPage | query | integer | No | 1–100, default 20 |
status | query | completed · cancelled | No | Orders are created already paid (debited from the balance). completed — paid and delivered (credentials available immediately). |
productId | query | string | No | Product id from the catalogue. Values for Droidkeep: . Clients must tolerate unknown values. |
Response 200 OK
{
"data": [
{
"id": "ord_4f8k2m9q",
"status": "completed",
"productId": "residential",
"planId": "PLAN_ID",
"planName": "PLAN_NAME",
"quantity": 0,
"unitPrice": "29.00",
"subtotal": "29.00",
"discount": "29.00",
"total": "29.00",
"promoCode": null,
"currency": "USD",
"topUpId": null,
"options": {
"country": "US",
"carrier": "CARRIER",
"city": "CITY",
"subscriptionId": "SUBSCRIPTION_ID",
"portId": "PORT_ID",
"autoRenew": false,
"domains": [
{
"name": "example.com",
"years": 1,
"privacy": false,
"action": "register",
"autoRenew": false,
"authCode": null,
"authCodeProvided": false,
"ownership": "self"
}
],
"registrant": {
"email": "EMAIL",
"name": "NAME",
"organization": "ORGANIZATION",
"country": "COUNTRY",
"address": {
"street": "STREET",
"city": "CITY",
"state": "STATE",
"postalCode": "POSTAL_CODE"
},
"phone": "PHONE",
"eligibility": [
{
"tld": "eu",
"country": "COUNTRY",
"nexusCategory": "C11",
"purpose": "P1"
}
]
},
"nameservers": {
"mode": "default"
},
"agreements": {
"terms": true,
"registrantBenefits": true,
"acceptedAt": "2026-10-05T14:03:11Z",
"termsUrl": null
},
"esim": [
{
"planId": "PLAN_ID",
"code": "CODE",
"qty": 1
}
],
"esimTopup": {
"iccid": "ICCID",
"planId": "PLAN_ID"
}
},
"fulfillment": null,
"createdAt": "2026-10-05T14:03:11Z",
"paidAt": "2026-10-05T14:03:11Z"
}
],
"pagination": {
"page": 1,
"perPage": 20,
"total": 1,
"totalPages": 1
}
}Code examples
curl -s "https://droidkeep.com/api/v1/orders" \
-H "Authorization: Bearer $API_KEY"import os
import requests
API = "https://droidkeep.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
r = requests.get(f"{API}/orders", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())// Node.js 18+ (built-in fetch), ES module
const API = 'https://droidkeep.com/api/v1';
const res = await fetch(`${API}/orders`, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());Get an order
GET/v1/orders/{orderId}
Authentication: API key in the Authorization: Bearer API_KEY header.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orderId | path | string | Yes | — |
Response 200 OK
{
"id": "ord_4f8k2m9q",
"status": "completed",
"productId": "residential",
"planId": "PLAN_ID",
"planName": "PLAN_NAME",
"quantity": 0,
"unitPrice": "29.00",
"subtotal": "29.00",
"discount": "29.00",
"total": "29.00",
"promoCode": null,
"currency": "USD",
"topUpId": null,
"options": {
"country": "US",
"carrier": "CARRIER",
"city": "CITY",
"subscriptionId": "SUBSCRIPTION_ID",
"portId": "PORT_ID",
"autoRenew": false,
"domains": [
{
"name": "example.com",
"years": 1,
"privacy": false,
"action": "register",
"autoRenew": false,
"authCode": null,
"authCodeProvided": false,
"ownership": "self"
}
],
"registrant": {
"email": "EMAIL",
"name": "NAME",
"organization": "ORGANIZATION",
"country": "COUNTRY",
"address": {
"street": "STREET",
"city": "CITY",
"state": "STATE",
"postalCode": "POSTAL_CODE"
},
"phone": "PHONE",
"eligibility": [
{
"tld": "eu",
"country": "COUNTRY",
"nexusCategory": "C11",
"purpose": "P1"
}
]
},
"nameservers": {
"mode": "default"
},
"agreements": {
"terms": true,
"registrantBenefits": true,
"acceptedAt": "2026-10-05T14:03:11Z",
"termsUrl": null
},
"esim": [
{
"planId": "PLAN_ID",
"code": "CODE",
"qty": 1
}
],
"esimTopup": {
"iccid": "ICCID",
"planId": "PLAN_ID"
}
},
"fulfillment": null,
"createdAt": "2026-10-05T14:03:11Z",
"paidAt": "2026-10-05T14:03:11Z"
}Code examples
curl -s "https://droidkeep.com/api/v1/orders/ord_4f8k2m9q" \
-H "Authorization: Bearer $API_KEY"import os
import requests
API = "https://droidkeep.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
r = requests.get(f"{API}/orders/ord_4f8k2m9q", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())// Node.js 18+ (built-in fetch), ES module
const API = 'https://droidkeep.com/api/v1';
const res = await fetch(`${API}/orders/ord_4f8k2m9q`, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());