Turn renewals or automatic renewal on or off

PATCH

/v1/services/{id}

const url = 'https://api.trueproxies.com/v1/services/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"auto_pay":true,"auto_pay_consent":{"disclosure_text":"example","disclosure_version":"example"},"label":"example","renewals_enabled":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://api.trueproxies.com/v1/services/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "auto_pay": true, "auto_pay_consent": { "disclosure_text": "example", "disclosure_version": "example" }, "label": "example", "renewals_enabled": true }'

Set renewals_enabled or auto_pay. Requires billing:write; reseller:purchase also permits this operation. Add customer_id to change a managed customer’s service, which additionally requires reseller:purchase: a managed customer’s renewal is paid from the wallet automatically. Managed customers’ services start with renewals off. Turning renewals off cancels an open renewal invoice and turns automatic renewal off. Free trials and comparison passes cannot be renewed. auto_pay charges the saved card for renewals (for automatic top-up on GB plans); turning it on needs a saved card and auto_pay_consent, the exact sentence the customer saw, and turning it off takes effect at once. Managed customers’ services cannot use automatic renewal.

Authorizations

customerAPIKey

Parameters

Path Parameters

required

string format: uuid

Query Parameters

customer_id

string format: uuid

Owned sub-customer UUID. Resellers only; reads require reseller:read and writes reseller:purchase in addition to the operation scope. X-Customer-Id header is an alternative. Not allowed for me, wallet, trial, API keys, or reseller-management routes.

Request Body^required

application/json

object

auto_pay

Turns automatic renewal (automatic top-up on GB plans) on or off for this service. Off takes effect at once. On needs a saved card and auto_pay_consent, and cannot be sent with renewals_enabled false on a plan that renews.

boolean

auto_pay_consent

Required when auto_pay is true.

object

disclosure_text

required

Refused when blank or longer than 1000 characters, so the stored sentence is exactly what was shown.

string

>= 1 characters <= 1000 characters

disclosure_version

required

string

>= 1 characters <= 64 characters

label

Your own name for this service, shown instead of the plan name. Leading and trailing spaces are trimmed; an empty string clears it. No line breaks or control characters.

string

<= 40 characters

renewals_enabled

boolean

Example^generated

{
  "auto_pay": true,
  "auto_pay_consent": {
    "disclosure_text": "example",
    "disclosure_version": "example"
  },
  "label": "example",
  "renewals_enabled": true
}

Responses

200

application/json

object

auto_pay

required

Automatic renewal is on (automatic top-up on GB plans). The saved card is charged without the customer paying the invoice.

boolean

auto_pay_available

required

Automatic renewal can be turned on for this service now.

boolean

auto_pay_last_failure

required

Any of:

object
null

object

required

string format: date-time

reason

required

string

billing_read_only

required

Existing access remains available, but this service cannot be topped up or renewed. New plan purchases are separate.

boolean

capabilities

required

Array<string>

city

string

comparison_pass

Free private comparison with fixed speed and expiry; cannot be purchased, topped up or renewed.

boolean

connects_per_second

required

Effective limit for this service.

integer

created_at

required

string format: date-time

depleted

boolean

display_name

required

Unlimited service names reflect their actual speed and term; offer_key retains the original billing plan.

string

expires_at

string format: date-time

grace_until

string format: date-time

host

required

string

required

Internal API identifier. Use reference for customer-facing display.

string format: uuid

ips

The service’s IPs in order, for isp_dedicated; empty until they are set up.

Array<object>

One IP of an isp_dedicated service and the gateway port that reaches it.

object

exit_ip

required

The IP traffic leaves from; null until it is known.

string | null

host

required

string

index

required

integer

port

required

integer

label

The customer’s own name for this service. Absent when not set; show display_name then.

string

<= 40 characters

max_connections

required

Effective limit for this service.

integer

offer_key

required

string

pool

A carrier sold as isp_dedicated, a country and the provider its IPs are registered to.

object

carrier

required

string

country

required

string

in_stock

required

boolean

key

required

string

terms

required

Array<string>

Allowed values: day week month

ports

required

object

http

required

integer

https

required

integer

socks5

required

integer

product

required

string

Allowed values: residential_ipv4_gb residential_ipv4_unlimited datacenter_ipv6 trial residential_ipv6 isp_dedicated residential_ipv4_premium residential_ipv4_lite residential_ipv4_unlimited_pro

quantity

IPs bought, for isp_dedicated.

integer

>= 1

reference

required

Stable, unique customer-facing reference.

string

/^SVC-[0-9]{6,}$/

renewal_price_cents

What the next renewal, or a top-up with the same pack, charges. A service keeps the price it was bought or last changed plan at when the catalog price changes. Absent when the service does not renew.

integer format: int64

renewals_enabled

required

boolean

speed_bps

0 for paid residential_ipv4_gb means no additional TrueProxies speed cap. Private comparison passes have a fixed 50000000 bps cap. residential_ipv4_unlimited retains its positive plan speed. Upstream capacity and availability still apply. Trials and datacenter plans retain their speed limits.

integer format: int64

starts_at

string format: date-time

status

required

string

Allowed values: pending active expired closed suspended failed

term

string

Allowed values: hour day week month

term_label

Actual fixed duration for a free Unlimited grant, such as 3 hours. Overrides the recurring term label in customer views.

string

trial_product

The Unlimited product a free trial (offer_key ipv4_unlimited_trial_1h) runs as, or will start as before its first request. Upgrade plan moves the trial within this product. Absent on other services.

string

Allowed values: residential_ipv4_unlimited residential_ipv4_unlimited_pro

trial_started_at

First recorded trial traffic; absent until the first request starts the 30-minute window.

string format: date-time

udp_ports

The only destination ports UDP over SOCKS5 reaches on this service (443 and 19302 on Unlimited Pro and on a free trial that runs as Unlimited Pro). Absent when any port the gateway allows works.

Array<integer>

usage_source

required

string

Allowed values: node

username_base

required

string

whitelist_entries

integer

Example

{
  "pool": {
    "terms": [
      "day"
    ]
  },
  "product": "residential_ipv4_gb",
  "reference": "SVC-001001",
  "status": "pending",
  "term": "hour",
  "trial_product": "residential_ipv4_unlimited",
  "usage_source": "node"
}

400

Error

application/json

object

code

required

string

Allowed values: BAD_REQUEST UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED SERVICE_UNAVAILABLE OFFER_UNAVAILABLE CITY_UNAVAILABLE CAPACITY_UNAVAILABLE INVOICE_NOT_PAYABLE PROVIDER_ERROR PIPE_UNAVAILABLE TRIAL_NOT_ELIGIBLE EMAIL_UNVERIFIED INTERNAL

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

401

Error

application/json

object

code

required

string

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

403

Error

application/json

object

code

required

string

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

404

Error

application/json

object

code

required

string

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

409

Error

application/json

object

code

required

string

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

429

Error

application/json

object

code

required

string

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

500

Error

application/json

object

code

required

string

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

503

Error

application/json

object

code

required

string

details

What a client needs to act on the error (ids, flags), never display text.

object

key

additional properties

any

message

required

string

Example

{
  "code": "BAD_REQUEST"
}

Turn renewals or automatic renewal on or off

Authorizations

Parameters

Path Parameters

Query Parameters

Request Bodyrequired

Examplegenerated

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

409

Example

429

Example

500

Example

503

Example

Request Body^required

Example^generated