{"openapi":"3.1.0","info":{"title":"VPS Ray Reseller API","version":"1.1.0","description":"Customer-scoped catalog, quotes, services, invoices and unpaid orders. Keys never confer admin permissions. Pay through the portal, or explicitly authorize wallet:pay to pay an owned invoice from prepaid credit."},"servers":[{"url":"https://vpsray.com/api/reseller/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"vpr_ token created in your account’s API access page or issued by an authorized VPS Ray administrator"}}},"paths":{"/catalog":{"get":{"summary":"List published services and account-tier prices","description":"Required scope: catalog:read Lists return nextOffset or null. Catalog is the last synced inventory; call /quotes/{id} before ordering.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Successful response. Monetary values are integer minor units.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/quotes/{id}":{"get":{"summary":"Refresh service pricing and get a current account quote","description":"Required scope: catalog:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Monetary values are integer minor units.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"409":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/services":{"get":{"summary":"List services owned by this key’s customer","description":"Required scope: services:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Successful response. Monetary values are integer minor units.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/services/{id}":{"get":{"summary":"Read an owned service","description":"Required scope: services:read A malformed saved configuration is marked configurationStatus=unavailable; confirmed infrastructure and service status remain available.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"refresh","in":"query","description":"Set 1 to wait for a supplier refresh, subject to supplier rate limits. Default returns saved, timestamped evidence and schedules a refresh. infrastructure.freshness distinguishes current from stale evidence.","schema":{"type":"integer","enum":[1]}}],"responses":{"200":{"description":"Successful response. Monetary values are integer minor units.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/invoices":{"get":{"summary":"List owned invoices","description":"Required scope: invoices:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Successful response. Monetary values are integer minor units.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/invoices/{id}":{"get":{"summary":"Read an owned invoice","description":"Required scope: invoices:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Monetary values are integer minor units.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/orders":{"post":{"summary":"Create one unpaid order using a reviewed quote","description":"Requires orders:write. Reusing an Idempotency-Key returns the original invoice. Live checkout must be enabled. This endpoint creates an unpaid invoice.","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9-]{1,80}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["planId","cycle","location","hostname","provider","expectedAmount","billing"],"properties":{"planId":{"type":"string"},"cycle":{"enum":["monthly","quarterly","semiannually","annually","biennially","triennially"]},"location":{"type":"string","description":"Exact quote location option"},"hostname":{"type":"string"},"os":{"type":"string","description":"Required for VPS and dedicated servers; use an exact quote osChoice"},"provider":{"enum":["nmi","cryptomus","binance","wallet"]},"walletCurrency":{"enum":["USD","USDT"],"description":"Required when provider is wallet"},"expectedAmount":{"type":"integer","minimum":1,"description":"Quote prices[cycle].total in cents; Binance quotes use fixed USDT minor units"},"expectedRenewalAmount":{"type":"integer","description":"Required for Namecheap domains; quote renewal in cents"},"billing":{"type":"object","required":["firstName","lastName","address","city","state","postcode","country","phone"],"properties":{"firstName":{"type":"string","maxLength":160},"lastName":{"type":"string","maxLength":160},"address":{"type":"string","maxLength":160},"city":{"type":"string","maxLength":160},"state":{"type":"string","maxLength":160},"postcode":{"type":"string","maxLength":160},"country":{"type":"string","maxLength":160},"phone":{"type":"string","maxLength":160}}},"serverPassword":{"type":"string","writeOnly":true,"description":"Optional initial password for supported server plans. Use the password rules shown in the quote. Never log or persist this request in plaintext."},"serviceName":{"type":"string","maxLength":80,"description":"Optional display name for a server."}}}}}},"responses":{"200":{"description":"Unpaid invoice or the original invoice for an idempotent replay","content":{"application/json":{"schema":{"type":"object","properties":{"invoice":{"type":"object","properties":{"id":{"type":"string"},"serviceId":{"type":"string"},"amount":{"type":"integer"},"currency":{"enum":["USD","USDT"]},"status":{"type":"string"},"paymentPath":{"type":"string"},"paymentUrl":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"413":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"415":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"503":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/account":{"get":{"summary":"Verify your key, scopes, expiry and assigned pricing tier","description":"Accepts any valid API key; returns only that key’s account identity, scopes, expiry and rate budget. No orders, funds or supplier requests are created.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response. Monetary values are integer minor units.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/balance":{"get":{"summary":"Read your prepaid wallet balances in integer cents","description":"Required scope: wallet:read","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Successful response. Monetary values are integer minor units.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/invoices/{id}/pay":{"post":{"summary":"Pay an existing invoice from your prepaid wallet","description":"Requires wallet:pay. Deduplicated by invoice ID. No card charge. The complete invoice amount is debited atomically once; insufficient credit does not debit the wallet. Payment queues activation. Read the service until active; paid does not mean delivered.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The existing invoice after payment, including on an idempotent replay"},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"503":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/domains/check":{"get":{"summary":"Check domain availability before registration","description":"Required scope: catalog:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","example":"example.com"}}],"responses":{"200":{"description":"Successful response. Monetary values are integer minor units.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"403":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}}}