# 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.<br>

```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"}}}}}}}}}
```

## 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.<br>

```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":{"type":"object"}}}}}},"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.<br>

```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"}}},"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"},"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"]}}}}}}}}}
```

## POST /user/api/orders/{id}/renew

> Renew order

```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","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"}}}}}}}}}
```