# Subscriptions

Subscription viewing endpoints

## List all subscriptions

> Returns all Paddle subscriptions for the authenticated user with pagination. Use portal URLs to manage subscriptions.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies User API","version":"1.0.0"},"tags":[{"name":"Subscriptions","description":"Subscription viewing endpoints"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page.","name":"X-API-KEY","in":"header"}},"schemas":{"Subscription":{"properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","canceled","past_due","paused","trialing","inactive"]},"billing_cycle":{"type":"string"},"currency_code":{"type":"string"},"current_period_starts_at":{"type":"string","format":"date-time","nullable":true},"current_period_ends_at":{"type":"string","format":"date-time","nullable":true},"next_billed_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"canceled_at":{"type":"string","format":"date-time","nullable":true},"paused_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"has_scheduled_cancellation":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"portal_urls":{"properties":{"cancel":{"type":"string","format":"uri","nullable":true},"update_payment_method":{"type":"string","format":"uri","nullable":true}},"type":"object","nullable":true},"sub_user":{"oneOf":[{"$ref":"#/components/schemas/SubUser"}],"nullable":true}},"type":"object"},"SubUser":{"title":"Sub-User","description":"A sub-user represents a proxy credential that can be used for authentication. Sub-users are associated with different proxy types (datacenter, residential, ISP, IPv6) and have their own bandwidth allocations and settings.","required":["uuid","name","type","status","created_at","updated_at"],"properties":{"uuid":{"description":"Unique identifier for the sub-user. Use this UUID in all API operations.","type":"string","format":"uuid"},"name":{"description":"Username for proxy authentication. This is the login credential used when connecting to the proxy server.","type":"string"},"type":{"description":"Proxy product type. Determines the IP pool and features available.","type":"string","enum":["datacenter","residential","ipv6","isp"]},"status":{"description":"Current status of the sub-user. Only \"active\" sub-users can be used for proxy connections.","type":"string","enum":["active","expired","suspended"]},"expires_at":{"description":"Expiration date/time in ISO 8601 format. Null for sub-users with no expiration. After expiration, status changes to \"expired\".","type":"string","format":"date-time","nullable":true},"created_at":{"description":"Creation timestamp in ISO 8601 format.","type":"string","format":"date-time"},"updated_at":{"description":"Last update timestamp in ISO 8601 format.","type":"string","format":"date-time"},"credentials":{"description":"Proxy authentication credentials. Only included when `include=credentials` is specified.","properties":{"username":{"description":"Proxy authentication username.","type":"string"},"password":{"description":"Proxy authentication password.","type":"string"}},"type":"object","nullable":true},"traffic":{"description":"Bandwidth usage information. Only included when `include=traffic` is specified.","properties":{"used":{"description":"Bandwidth used in GB.","type":"number","format":"float"},"total":{"description":"Total bandwidth allocation in GB.","type":"number","format":"float"},"remaining":{"description":"Remaining bandwidth in GB.","type":"number","format":"float"},"unit":{"description":"Unit of measurement.","type":"string"}},"type":"object","nullable":true},"proxy_settings":{"description":"Advanced proxy settings. Only included when `include=proxy_settings` is specified.","properties":{"whitelisted_ips":{"description":"Allowed IP addresses.","type":"array","items":{"type":"string"}},"country_list":{"description":"Country distribution for datacenter/ISP.","type":"object"},"high_priority":{"description":"High priority routing enabled.","type":"boolean"},"high_concurrency":{"description":"High concurrency mode enabled.","type":"boolean"},"purchased_ip_count":{"description":"Number of IPs purchased.","type":"integer","nullable":true}},"type":"object","nullable":true},"ip_list":{"description":"List of assigned proxy IPs. Only available for ISP and Datacenter sub-users. Included when `include=ip_list` is specified.","type":"array","items":{"type":"string"},"nullable":true}},"type":"object"}},"responses":{"Unauthorized":{"description":"Authentication failed. Ensure your API key is valid and included in the X-API-KEY header.","headers":{"WWW-Authenticate":{"description":"Authentication scheme hint","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"error":{"properties":{"code":{"type":"string","enum":["API_KEY_MISSING","INVALID_API_KEY","USER_NOT_FOUND"]},"message":{"type":"string"}},"type":"object"}},"type":"object"}}}}}},"paths":{"/subscriptions":{"get":{"tags":["Subscriptions"],"summary":"List all subscriptions","description":"Returns all Paddle subscriptions for the authenticated user with pagination. Use portal URLs to manage subscriptions.","operationId":"1d87b72d732677a952432dd6266c7270","parameters":[{"name":"filter[status]","in":"query","description":"Filter by subscription status","required":false,"schema":{"type":"string","enum":["active","canceled","past_due","paused","trialing","all"]}},{"name":"page","in":"query","description":"Page number for pagination","required":false,"schema":{"type":"integer","default":1,"minimum":1}},{"name":"per_page","in":"query","description":"Number of items per page (max 100)","required":false,"schema":{"type":"integer","default":10,"maximum":100,"minimum":1}},{"name":"include","in":"query","description":"Comma-separated list of relations to include (portal_urls, sub_user, invoices)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of subscriptions","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"meta":{"properties":{"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"from":{"type":"integer"},"to":{"type":"integer"}},"type":"object"}},"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Get subscription details

> Returns details for a specific subscription including Paddle portal URLs for management.

```json
{"openapi":"3.0.0","info":{"title":"PlainProxies User API","version":"1.0.0"},"tags":[{"name":"Subscriptions","description":"Subscription viewing endpoints"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"API Key authentication. Get your key from the Dashboard Settings page.","name":"X-API-KEY","in":"header"}},"schemas":{"Subscription":{"properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","canceled","past_due","paused","trialing","inactive"]},"billing_cycle":{"type":"string"},"currency_code":{"type":"string"},"current_period_starts_at":{"type":"string","format":"date-time","nullable":true},"current_period_ends_at":{"type":"string","format":"date-time","nullable":true},"next_billed_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"canceled_at":{"type":"string","format":"date-time","nullable":true},"paused_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"has_scheduled_cancellation":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"portal_urls":{"properties":{"cancel":{"type":"string","format":"uri","nullable":true},"update_payment_method":{"type":"string","format":"uri","nullable":true}},"type":"object","nullable":true},"sub_user":{"oneOf":[{"$ref":"#/components/schemas/SubUser"}],"nullable":true}},"type":"object"},"SubUser":{"title":"Sub-User","description":"A sub-user represents a proxy credential that can be used for authentication. Sub-users are associated with different proxy types (datacenter, residential, ISP, IPv6) and have their own bandwidth allocations and settings.","required":["uuid","name","type","status","created_at","updated_at"],"properties":{"uuid":{"description":"Unique identifier for the sub-user. Use this UUID in all API operations.","type":"string","format":"uuid"},"name":{"description":"Username for proxy authentication. This is the login credential used when connecting to the proxy server.","type":"string"},"type":{"description":"Proxy product type. Determines the IP pool and features available.","type":"string","enum":["datacenter","residential","ipv6","isp"]},"status":{"description":"Current status of the sub-user. Only \"active\" sub-users can be used for proxy connections.","type":"string","enum":["active","expired","suspended"]},"expires_at":{"description":"Expiration date/time in ISO 8601 format. Null for sub-users with no expiration. After expiration, status changes to \"expired\".","type":"string","format":"date-time","nullable":true},"created_at":{"description":"Creation timestamp in ISO 8601 format.","type":"string","format":"date-time"},"updated_at":{"description":"Last update timestamp in ISO 8601 format.","type":"string","format":"date-time"},"credentials":{"description":"Proxy authentication credentials. Only included when `include=credentials` is specified.","properties":{"username":{"description":"Proxy authentication username.","type":"string"},"password":{"description":"Proxy authentication password.","type":"string"}},"type":"object","nullable":true},"traffic":{"description":"Bandwidth usage information. Only included when `include=traffic` is specified.","properties":{"used":{"description":"Bandwidth used in GB.","type":"number","format":"float"},"total":{"description":"Total bandwidth allocation in GB.","type":"number","format":"float"},"remaining":{"description":"Remaining bandwidth in GB.","type":"number","format":"float"},"unit":{"description":"Unit of measurement.","type":"string"}},"type":"object","nullable":true},"proxy_settings":{"description":"Advanced proxy settings. Only included when `include=proxy_settings` is specified.","properties":{"whitelisted_ips":{"description":"Allowed IP addresses.","type":"array","items":{"type":"string"}},"country_list":{"description":"Country distribution for datacenter/ISP.","type":"object"},"high_priority":{"description":"High priority routing enabled.","type":"boolean"},"high_concurrency":{"description":"High concurrency mode enabled.","type":"boolean"},"purchased_ip_count":{"description":"Number of IPs purchased.","type":"integer","nullable":true}},"type":"object","nullable":true},"ip_list":{"description":"List of assigned proxy IPs. Only available for ISP and Datacenter sub-users. Included when `include=ip_list` is specified.","type":"array","items":{"type":"string"},"nullable":true}},"type":"object"}},"responses":{"Unauthorized":{"description":"Authentication failed. Ensure your API key is valid and included in the X-API-KEY header.","headers":{"WWW-Authenticate":{"description":"Authentication scheme hint","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"error":{"properties":{"code":{"type":"string","enum":["API_KEY_MISSING","INVALID_API_KEY","USER_NOT_FOUND"]},"message":{"type":"string"}},"type":"object"}},"type":"object"}}}},"NotFound":{"description":"The requested resource does not exist or you do not have access to it.","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"}},"type":"object"}}}}}},"paths":{"/subscriptions/{uuid}":{"get":{"tags":["Subscriptions"],"summary":"Get subscription details","description":"Returns details for a specific subscription including Paddle portal URLs for management.","operationId":"b8fa3d8074f24eedaa4bd297d3a01be9","parameters":[{"name":"uuid","in":"path","description":"Subscription UUID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"include","in":"query","description":"Comma-separated list of relations to include (portal_urls, sub_user, invoices)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription details","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Subscription"}},"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```


---

# 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.plainproxies.com/api-documentation/billing-and-invoicing/subscriptions.md?ask=<question>
```

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.