# General
General operations (profile, orders, reference data)
## Create and pay for an order
> Purchase by product name, location, and cycle.\
> For Datacenter/ISP, location is required.\
> For Standart Residential Proxy, location is not required.
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"PurchaseRequestDcIsp":{"type":"object","description":"Purchase for Datacenter/ISP — the location field is required.","properties":{"product":{"type":"string","enum":["Datacenter Proxy","ISP Proxy"]},"location":{"type":"string"},"cycle":{"type":"string"},"quantity":{"type":"integer","minimum":1,"default":1},"promo_code":{"type":"string","nullable":true},"auto_renewal":{"type":"boolean","default":false}},"required":["product","location","cycle"]},"PurchaseRequestResidentialStandard":{"type":"object","description":"Purchase for Standart Residential Proxy — location is not required; the cycle is fixed (lifetime).","properties":{"product":{"type":"string","enum":["Standart Residential Proxy"]},"quantity":{"type":"integer","minimum":1,"default":1},"promo_code":{"type":"string","nullable":true}},"required":["product"]},"PurchaseRequestResidentialPremium":{"type":"object","description":"Purchase for Premium Residential Proxy — location is not required; the cycle is fixed (lifetime).","properties":{"product":{"type":"string","enum":["Premium Residential Proxy"]},"quantity":{"type":"integer","minimum":1,"default":1},"promo_code":{"type":"string","nullable":true}},"required":["product"]},"PurchaseRequestResidentialUnmetered":{"type":"object","description":"Purchase for Unmetered Residential proxy — supports auto-renewal.","properties":{"product":{"type":"string","enum":["Unmetered Residential proxy"]},"cycle":{"type":"string"},"promo_code":{"type":"string","nullable":true},"auto_renewal":{"type":"boolean","default":false}},"required":["product","cycle"]},"PurchaseRequest":{"type":"object","properties":{"product":{"type":"string"},"location":{"type":"string","nullable":true},"cycle":{"type":"string"},"quantity":{"type":"integer","minimum":1,"default":1},"promo_code":{"type":"string","nullable":true},"auto_renewal":{"type":"boolean","default":false}},"required":["product","cycle"]},"PurchaseResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"order_id":{"type":"integer"}},"required":["success","message","order_id"]},"ApiError":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]}}},"paths":{"/user/api/orders/purchase":{"post":{"tags":["General"],"summary":"Create and pay for an order","description":"Purchase by product name, location, and cycle.\nFor Datacenter/ISP, location is required.\nFor Standart Residential Proxy, location is not required.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PurchaseRequestDcIsp"},{"$ref":"#/components/schemas/PurchaseRequestResidentialStandard"},{"$ref":"#/components/schemas/PurchaseRequestResidentialPremium"},{"$ref":"#/components/schemas/PurchaseRequestResidentialUnmetered"},{"$ref":"#/components/schemas/PurchaseRequest"}]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponse"}}}},"400":{"description":"Validation/balance error/insufficient stock","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```
## Calculate order price
> Calculates price by product name, cycle name and quantity.\
> Uses the same validation rules as purchase (allowed billing cycles, promo rules).
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ApiError":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]}}},"paths":{"/user/api/orders/calculate":{"get":{"tags":["General"],"summary":"Calculate order price","description":"Calculates price by product name, cycle name and quantity.\nUses the same validation rules as purchase (allowed billing cycles, promo rules).\n","parameters":[{"in":"query","name":"product","required":true,"schema":{"type":"string"}},{"in":"query","name":"location","required":false,"schema":{"type":"string","nullable":true}},{"in":"query","name":"cycle","required":false,"schema":{"type":"string","nullable":true}},{"in":"query","name":"quantity","required":false,"schema":{"type":"integer","nullable":true}},{"in":"query","name":"promo_code","required":false,"schema":{"type":"string","nullable":true}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"original_price":{"type":"integer"},"final_price":{"type":"integer"},"discount_percent":{"type":"integer"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```
## Change the order billing cycle
> Changes the billing cycle by cycle name. Only for Datacenter & ISP proxies.\
> If the promo code is not available for the selected cycle, it will be automatically reset.
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ApiError":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]}}},"paths":{"/user/api/orders/change-billing-cycle/{order_id}":{"post":{"tags":["General"],"summary":"Change the order billing cycle","description":"Changes the billing cycle by cycle name. Only for Datacenter & ISP proxies.\nIf the promo code is not available for the selected cycle, it will be automatically reset.\n","parameters":[{"in":"path","name":"order_id","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cycle":{"type":"string"}},"required":["cycle"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"order_id":{"type":"integer"},"original_price":{"type":"integer"},"final_price":{"type":"integer"},"discount_percent":{"type":"integer"}}}}}},"400":{"description":"Invalid product or cycle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Cycle is not available for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```
## Change order auto-renewal
> Enable/disable auto-renewal. Only for Datacenter & ISP proxies.
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ApiError":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]}}},"paths":{"/user/api/orders/edit-auto-renewal/{order_id}":{"post":{"tags":["General"],"summary":"Change order auto-renewal","description":"Enable/disable auto-renewal. Only for Datacenter & ISP proxies.\n","parameters":[{"in":"path","name":"order_id","required":true,"schema":{"type":"integer"}},{"in":"query","name":"auto_renewal","required":true,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid product for this operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```
## Get products and their cycles
> Returns API products with the names of available cycles.
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ProductWithCycles":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"cycles":{"type":"array","items":{"type":"string"}}},"required":["name","cycles"]}}},"paths":{"/user/api/proxies/products":{"get":{"tags":["General"],"summary":"Get products and their cycles","description":"Returns API products with the names of available cycles.","responses":{"200":{"description":"Product list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductWithCycles"}}},"required":["success","products"]}}}}}}}}}
```
## Get the available number of proxies
> Returns the total available quantity for all products.
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AvailableCountResponse":{"type":"object","properties":{"country":{"type":"string"},"product":{"type":"string"},"amount":{"type":"integer"}},"required":["country","product","amount"]}}},"paths":{"/user/api/proxies/available-count":{"get":{"tags":["General"],"summary":"Get the available number of proxies","description":"Returns the total available quantity for all products.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AvailableCountResponse"}}}}}}}}}}
```
## GET /user/api/me
> User information
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ApiMeResponse":{"type":"object","properties":{"email":{"type":"string"},"active_orders":{"type":"integer"},"wallet_balance":{"type":"integer","description":"in cents"}},"required":["email","active_orders","wallet_balance"]}}},"paths":{"/user/api/me":{"get":{"tags":["General"],"summary":"User information","responses":{"200":{"description":"Profile data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiMeResponse"}}}}}}}}}
```
## GET /user/api/orders
> Order list
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/user/api/orders":{"get":{"tags":["General"],"summary":"Order list","parameters":[{"in":"query","name":"status","required":true,"description":"active | on-hold | cancelled | all","schema":{"type":"string"}},{"in":"query","name":"offset","required":false,"description":"Result offset (default 0)","schema":{"type":"integer","minimum":0}},{"in":"query","name":"limit","required":false,"description":"Page size (1..100, default 20)","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Order list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"orders":{"type":"array","items":{"type":"object","properties":{"order_id":{"type":"integer"},"product_id":{"type":"integer"},"product_name":{"type":"string"},"cycle_id":{"type":"integer"},"cycle_name":{"type":"string"},"expires_at":{"type":"string","nullable":true,"description":"ISO8601 expiration time"},"auto_renewal":{"type":"boolean","nullable":true},"tag":{"type":"string","nullable":true}},"required":["order_id","product_id","product_name","cycle_id","cycle_name"]}},"count":{"type":"integer","description":"Number of orders in the current result set"},"prev":{"type":"string","nullable":true,"description":"Previous page URI"},"next":{"type":"string","nullable":true,"description":"Next page URI"}},"required":["success","orders"]}}}}}}}}}
```
## GET /user/api/orders/{id}
> Get order information
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AddonLine":{"type":"object","description":"A single add-on line stored on an order","properties":{"addon_key":{"type":"string"},"catalog_id":{"type":"integer"},"qty":{"type":"integer","description":"Active units for the current period"},"price_per_unit":{"type":"integer","description":"Price per unit in cents at time of purchase"},"pending":{"description":"Scheduled change to apply on next renewal (null if none)","nullable":true,"type":"object","properties":{"action":{"type":"string","enum":["cancel","downgrade"]},"next_qty":{"type":"integer","description":"Target qty after downgrade (only present for downgrade action)"}}}}}}},"paths":{"/user/api/orders/{id}":{"get":{"tags":["General"],"summary":"Get order information","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Order information","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"order":{"type":"object","properties":{"order_id":{"type":"integer"},"product_name":{"type":"string"},"cycle_name":{"type":"string"},"quantity":{"type":"integer"},"price_paid":{"type":"integer","description":"Base subscription price in cents"},"addons_price_paid":{"type":"integer","description":"Total add-on cost in cents"},"addons":{"type":"array","description":"Add-on lines attached to this order","items":{"$ref":"#/components/schemas/AddonLine"}},"p0f_slots_available":{"type":"integer","description":"Active p0f signature slots (from add-ons)"},"p0f_slots_used":{"type":"integer","description":"Slots currently occupied by signed proxies"},"p0f_slots_next":{"type":"integer","description":"Slots that will be active after next renewal"},"status":{"type":"string"},"created_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"promo_code":{"type":"string","nullable":true},"auto_renewal":{"type":"boolean","nullable":true},"tag":{"type":"string","nullable":true}}}},"required":["success","order"]}}}}}}}}}
```
## Renew order
> Renewal is available only when order status is \`on-hold\`.
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ApiSuccess":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"ApiError":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}},"required":["success","message"]}}},"paths":{"/user/api/orders/{id}/renew":{"post":{"tags":["General"],"summary":"Renew order","description":"Renewal is available only when order status is `on-hold`.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}},"400":{"description":"Insufficient balance/validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```
## POST /user/api/orders/{id}/tag
> Change order tag
```json
{"openapi":"3.0.3","info":{"title":"ProxyShard User API Billing","version":"1.0.0"},"tags":[{"name":"General","description":"General operations (profile, orders, reference data)"}],"servers":[{"url":"https://user-api.proxyshard.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ApiSuccess":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}},"paths":{"/user/api/orders/{id}/tag":{"post":{"tags":["General"],"summary":"Change order tag","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"string"}},"required":["tag"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSuccess"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.proxyshard.com/cn/yong-hu-api/general.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.