# API For Billing

## List billing records

> Returns a paginated list of billing records for the authenticated user, with optional filters (type, date range, status, payment method) and sorting.

```json
{"openapi":"3.1.1","info":{"title":"Billing","version":"1.0"},"servers":[{"url":"https://sandbox.9proxy.com"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"api-key","in":"query"}},"schemas":{"ResponseListBilling":{"type":"object","description":"Billing records list response payload.","properties":{"success":{"type":"boolean","description":"Indicates whether the request was successful."},"message":{"type":"string","description":"Human-readable response message."},"result":{"type":"object","description":"Paginated response data.","properties":{"items":{"type":"array","description":"List of billing records.","items":{"$ref":"#/components/schemas/BillingInfo"}},"total_items":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."}}}}},"BillingInfo":{"type":"object","description":"Billing record details.","properties":{"id":{"type":"string","description":"Billing record ID."},"billing_number":{"type":"string","description":"Billing reference number."},"type":{"type":"integer","description":"Billing record type. 1: Purchase (data/IPs), 2: Wallet top-up"},"package_id":{"type":["number","null"],"description":"Associated package ID (if applicable)."},"account_id":{"type":"integer","description":"Account ID that owns this billing record."},"amount":{"type":"number","description":"Total billed amount."},"number_of_ips":{"type":["number","null"],"description":"Number of IPs granted (if applicable)."},"amount_traffic":{"type":["number","null"],"description":"Traffic amount granted (if applicable)."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"status":{"type":"integer","description":"Billing status. 0: pending, 1: success, -1: failed"},"created_at":{"type":"integer","description":"Billing creation timestamp."}}},"PaymentMethod":{"type":"integer","description":"1: Crypto\n2: Card\n3: Local Payment\n4: Wallet\n5: Income"},"ResponseBadRequestError":{"type":"object","description":"Response payload returned when the request is invalid.","properties":{"success":{"type":"boolean","description":"Indicates whether the request was successful."},"message":{"type":"string","description":"Human-readable response message."},"errors":{"type":"array","description":"List of error messages.","items":{"type":"string"}}}},"ResponseForbiddenError":{"type":"object","description":"Response payload returned when access is forbidden.","properties":{"success":{"type":"boolean","description":"Indicates whether the request was successful."},"message":{"type":"string","description":"Human-readable response message."},"errors":{"type":"array","description":"List of error messages.","items":{"type":"string"}}}}}},"paths":{"/client/v1/billings/get-list":{"get":{"summary":"List billing records","description":"Returns a paginated list of billing records for the authenticated user, with optional filters (type, date range, status, payment method) and sorting.","parameters":[{"schema":{"type":"integer"},"name":"limit","in":"query","required":false,"description":"Maximum number of items to return per page. Default: 30"},{"schema":{"type":"integer"},"name":"page","in":"query","required":false,"description":"Requested page number (1-based). Default: 1"},{"schema":{"type":"integer"},"name":"type","in":"query","required":false,"description":"Billing record type. 1: Purchase, 2: Wallet top-up"},{"schema":{"type":"string"},"name":"start_date","in":"query","required":false,"description":"Filter by start date (YYYY-MM-DD), e.g., 2025-08-01"},{"schema":{"type":"string"},"name":"end_date","in":"query","required":false,"description":"Filter by end date (YYYY-MM-DD), e.g., 2025-08-30"},{"schema":{"type":"string"},"name":"sort_by","in":"query","required":false,"description":"Field to sort by: id, amount, number_of_ips. Default: id"},{"schema":{"type":"string"},"name":"order_by","in":"query","required":false,"description":"Sort order: desc or asc. Default: desc"},{"schema":{"type":"integer"},"name":"status","in":"query","required":false,"description":"Billing status. 0: pending, 1: success, -1: failed"},{"schema":{"type":"integer"},"name":"payment_method","in":"query","required":false,"description":"Filter by payment method."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseListBilling"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseBadRequestError"}}}},"403":{"description":"Authentication error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseForbiddenError"}}}}}}}}}
```

## The BillingInfo object

```json
{"openapi":"3.1.1","info":{"title":"Billing","version":"1.0"},"components":{"schemas":{"BillingInfo":{"type":"object","description":"Billing record details.","properties":{"id":{"type":"string","description":"Billing record ID."},"billing_number":{"type":"string","description":"Billing reference number."},"type":{"type":"integer","description":"Billing record type. 1: Purchase (data/IPs), 2: Wallet top-up"},"package_id":{"type":["number","null"],"description":"Associated package ID (if applicable)."},"account_id":{"type":"integer","description":"Account ID that owns this billing record."},"amount":{"type":"number","description":"Total billed amount."},"number_of_ips":{"type":["number","null"],"description":"Number of IPs granted (if applicable)."},"amount_traffic":{"type":["number","null"],"description":"Traffic amount granted (if applicable)."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"status":{"type":"integer","description":"Billing status. 0: pending, 1: success, -1: failed"},"created_at":{"type":"integer","description":"Billing creation timestamp."}}},"PaymentMethod":{"type":"integer","description":"1: Crypto\n2: Card\n3: Local Payment\n4: Wallet\n5: Income"}}}}
```

## The PaymentMethod object

```json
{"openapi":"3.1.1","info":{"title":"Billing","version":"1.0"},"components":{"schemas":{"PaymentMethod":{"type":"integer","description":"1: Crypto\n2: Card\n3: Local Payment\n4: Wallet\n5: Income"}}}}
```

## The ResponseListBilling object

```json
{"openapi":"3.1.1","info":{"title":"Billing","version":"1.0"},"components":{"schemas":{"ResponseListBilling":{"type":"object","description":"Billing records list response payload.","properties":{"success":{"type":"boolean","description":"Indicates whether the request was successful."},"message":{"type":"string","description":"Human-readable response message."},"result":{"type":"object","description":"Paginated response data.","properties":{"items":{"type":"array","description":"List of billing records.","items":{"$ref":"#/components/schemas/BillingInfo"}},"total_items":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."}}}}},"BillingInfo":{"type":"object","description":"Billing record details.","properties":{"id":{"type":"string","description":"Billing record ID."},"billing_number":{"type":"string","description":"Billing reference number."},"type":{"type":"integer","description":"Billing record type. 1: Purchase (data/IPs), 2: Wallet top-up"},"package_id":{"type":["number","null"],"description":"Associated package ID (if applicable)."},"account_id":{"type":"integer","description":"Account ID that owns this billing record."},"amount":{"type":"number","description":"Total billed amount."},"number_of_ips":{"type":["number","null"],"description":"Number of IPs granted (if applicable)."},"amount_traffic":{"type":["number","null"],"description":"Traffic amount granted (if applicable)."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"status":{"type":"integer","description":"Billing status. 0: pending, 1: success, -1: failed"},"created_at":{"type":"integer","description":"Billing creation timestamp."}}},"PaymentMethod":{"type":"integer","description":"1: Crypto\n2: Card\n3: Local Payment\n4: Wallet\n5: Income"}}}}
```

## The ResponseForbiddenError object

```json
{"openapi":"3.1.1","info":{"title":"Billing","version":"1.0"},"components":{"schemas":{"ResponseForbiddenError":{"type":"object","description":"Response payload returned when access is forbidden.","properties":{"success":{"type":"boolean","description":"Indicates whether the request was successful."},"message":{"type":"string","description":"Human-readable response message."},"errors":{"type":"array","description":"List of error messages.","items":{"type":"string"}}}}}}}
```

## The ResponseBadRequestError object

```json
{"openapi":"3.1.1","info":{"title":"Billing","version":"1.0"},"components":{"schemas":{"ResponseBadRequestError":{"type":"object","description":"Response payload returned when the request is invalid.","properties":{"success":{"type":"boolean","description":"Indicates whether the request was successful."},"message":{"type":"string","description":"Human-readable response message."},"errors":{"type":"array","description":"List of error messages.","items":{"type":"string"}}}}}}}
```