Fixed addresses

Operations on a fixed address package (family: dedicated, product ipv4). Each one acts on the whole package: on all its addresses at once. On a traffic package these routes answer 422 unsupported_capability.

The operations available to a package are listed in capabilities of its card: prolong, credentials, replace, fingerprint, renewal.

Term and statuses

Status	What is happening	What you can do
`provisioning`	the package is being issued, up to 2 minutes	wait
`active`	the addresses work until `expires_at`	everything
`expired`	the term has ended, the addresses do not answer	extend before `extendable_until` - the same addresses come back
`closed`	`extendable_until` has passed, the addresses are released	only a new purchase
`suspended`	the package is disabled	contact support

Card fields related to the term:

Field	Meaning
`expires_at`	end of the paid term
`extendable_until`	until when a renewal brings back the same addresses
`credentials_retired`	`true` - the password was disabled after the term ended; a renewal issues a new one

When the term ends, package.expired arrives in the event log.

GET /api/v1/packages/{id}/prolong-options

Which periods the package can be extended for and what it costs you. Scope packages:read.

{
  "options": [
    {
      "period": "week",
      "price": "1.98"
    },
    {
      "period": "2_weeks",
      "price": "2.58"
    },
    {
      "period": "month",
      "price": "2.98"
    },
    {
      "period": "2_months",
      "price": "5.96"
    },
    {
      "period": "3_months",
      "price": "8.94"
    }
  ],
  "currency": "USD"
}

price is the price for the whole package, for all its addresses.

POST /api/v1/packages/{id}/prolong

Extend the package. Scope packages:write, Idempotency-Key is required: this is a charge. Body: {"period": "month"}, the period from prolong-options.

curl -X POST https://ipv.rent/api/v1/packages/57/prolong \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"period":"month"}'

{
  "order_id": 140,
  "package_id": 57,
  "status": "completed",
  "price": "2.98",
  "expires_at": "2026-12-04T12:00:00+00:00",
  "credentials_reissued": false
}

The period is added to the current expires_at, or, if the term has already ended, to the moment of renewal.
The addresses and login stay the same.
credentials_reissued: true - the old password was disabled and a new one issued; take it from the package card.
A renewal creates a separate order with applied_to_package_id.

Errors:

400 - invalid_body (no body or not JSON), validation_failed
404 - not_found
409 - idempotency_in_progress
422 - unknown_period, insufficient_balance, prolong_window_closed (the addresses can no longer be brought back - the package is closed, a new purchase is needed), unsupported_capability, purchase_refunded, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed, order_needs_attention, operation_indeterminate - as for the purchase

POST /api/v1/packages/{id}/renewal

Auto-renewal. Scope packages:write. Charges nothing.

curl -X POST https://ipv.rent/api/v1/packages/57/renewal \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"enabled":true,"period":"month"}'

Field	Meaning
`enabled`	required: `true` or `false`
`period`	the period to renew for each time; without the field the previous one stays

The response is the package card. How auto-renewal works:

it is on by default, the period is the one that was bought;
the charge happens one day before expires_at, at the price at that moment; the date and amount are in renewal.next_charge_at and renewal.next_charge_amount;
if there is not enough money, renewal.last_failure becomes insufficient_balance, and attempts repeat every few hours for another 3 days after expires_at;
after that auto-renewal switches itself off, renewal.disabled_at is filled in.

Errors: 400 invalid_body (no enabled); 404 not_found; 422 unknown_period, unsupported_capability.

POST /api/v1/packages/{id}/replace

Replace all addresses of the package with new ones in the same location. Scope packages:write. No body needed. Free of charge.

The replacement runs in the background. The response is 202 and the card with replacement.state: pending. Read the card until state changes, usually in under a minute:

`replacement.state`	Meaning
`pending`	replacement in progress
`done`	`addresses` holds the new addresses, the old ones do not work
`failed`	nothing changed, you can request it again

The login, password, term and fingerprint do not change. The next replacement is possible after 30 days: replace_available_at in the card shows when.

Errors:

404 - not_found
409 - replace_in_progress (a replacement is already running)
422 - package_expired (the term has ended - extend first), unsupported_capability
429 - replace_cooldown (the addresses were replaced recently; the date is in replace_available_at)

POST /api/v1/packages/{id}/fingerprint

p0f fingerprint: the addresses present themselves as the chosen OS and browser. One profile for the whole package. Scope packages:write. Free of charge.

curl -X POST https://ipv.rent/api/v1/packages/57/fingerprint \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"profile":"windows_chrome"}'

profile is a value from fingerprint.profiles of the card: windows_chrome, windows_edge, windows_firefox, android_chrome, macos_chrome. null turns spoofing off.

The new fingerprint applies in 2-3 minutes. Connections opened before the change keep the old one - reconnect.

Errors: 400 validation_failed (the profile is not in the list); 404 not_found; 422 package_expired, unsupported_capability.

Password

Password reissue is the shared route POST /api/v1/packages/{id}/password. The login does not change, the old password stops working immediately on all addresses of the package.