# Rentals, Unlimited and cancellation

Browse `GET /services?type=rent&countryCode=US`, then request `/services/{serviceId}/durations?countryCode=US&kind=rent`. Use the returned IDs, milliseconds and exact price. Available services and terms depend on stock and the account's store catalog.

**Unlimited** is a catalog service for a general rental, rather than a duration or a special API flag. Find its service ID in the rental catalog and quote it like any other service. The number can receive supported SMS during its active rental term. Service availability is not a guarantee that every external app will accept a number.

Buy with `POST /rentals`, a required `Idempotency-Key`, and `serviceId`, `countryCode`, `duration` and `maxPrice`. Optional fields are `providerId` and `description`. Do not request `alwaysOn` or `autoRenew` purchase options: these are currently rejected, although the OpenAPI DTO lists their names.

## Cancellation

`POST /rentals/{id}/cancel` cancels a rental only when the server considers it eligible. The cancellation window is **5 through 120 minutes after purchase, inclusive, provided no SMS has been received**. Read the order's `isCancelable` before offering cancellation; the server checks again when the request arrives. Pending transfers or renewals and provider restrictions can also prevent it.

A successful cancellation returns HTTP 200 with an empty body. Refund accounting follows confirmed supplier cancellation and the original payer. An ambiguous supplier outcome needs reconciliation; do not promise a refund before confirmation. After a timeout, read the order before retrying.

OTP verifications use `/verifications/{id}/cancel`; eligibility is also server-controlled through `isCancelable`. The rental's 5–120-minute rule must not be assumed to apply to OTP orders.

## Auto-renew

Eligible active rentals expose `canAutoRenew` and `isAutoRenewEnabled`. Reseller onboarding QA’s dashboard lets the customer set auto-renew; it is off by default. Eligible Reseller onboarding QA rentals use wallet-funded renewal for the same term, with the original purchase price as ceiling. The renewal worker checks each minute and starts renewal 15 minutes before expiry. Insufficient funds or a higher price disables renewal.


[Documentation index](https://onboarding-qa.textverified.org/en/store-docs/index)

## Unlimited carrier selection

US Unlimited rentals accept an optional `carrier` value: `att` for AT&T or `tmobile` for T-Mobile. Pass the same value to `GET /durations` and `POST /rentals`. Use only a returned duration and price; each choice has its own availability. Omission preserves the default routing. An explicit choice never falls back to the other carrier option. The selector is unavailable for other services or countries. Carrier labels follow the configured number supply; a delivered number’s physical carrier has not been independently verified.

Catalog prices refresh sitewide every five minutes. Browsing uses the shared cached snapshot; a purchase checks the current exact price and stock again. Save the selected carrier with the purchase Idempotency-Key: changing it under the same key returns a conflict.

## Optional US area code

US Unlimited SMS rentals on T-Mobile accept an optional three-digit `areaCode`, such as `212`. Selecting it adds **USD1.00 per rented number once at purchase**, with no added area-code fee on renewals. `Any area code` has no extra fee. Availability is term-specific and this option does not apply to AT&T, app-specific rentals, voice or other countries.

Pass `carrier=tmobile&areaCode=212` to the service duration query, then pass the same `carrier` and `areaCode` to `POST /rentals`. The returned `price` and your `maxPrice` must include the one-time fee. Changing the code under a reused `Idempotency-Key` returns a conflict. Omit `areaCode` for an unrestricted number.

The cached rental plans expose an optional `areaCodePrice`; the cached catalog includes a state-grouped area-code list when available. Code metadata is refreshed in the shared five-minute catalog job. If that list is unavailable, the dashboard accepts manual three-digit entry and validates availability when purchasing. The server checks exact stock, current cost and the delivered number's prefix; it never silently substitutes another area code. Unsupported selection or a higher current price is rejected before billing. Confirmed eligible cancellation refunds the original paid amount, including the area-code fee.