> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/user-api/resources/billing/tariff/tariff_tracker.md). # Tracker tariff Which tariff a device is on, and the rules governing a change to another. These operations read the [tariffs](/docs/navixy-api/user-api/resources/billing/tariff.md) a device may switch to, and perform the switch. A change is heavily constrained, and `tariff/tracker/list` exists so a caller can find out what is actually permitted rather than guessing. A user may move a tracker from tariff **t1** to tariff **t2** only when all of the following hold: 1. The tracker belongs to the user and is not a clone. 2. The tracker's tariff was last changed more than `tariff.freeze.period` ago, 30 days by default. 3. `t1.tariff_id` differs from `t2.tariff_id`, so the new tariff is genuinely a different one. 4. `t1.dealer_id` and `t2.dealer_id` both equal the user's effective dealer. 5. `t2.active` is 1, meaning the dealer has allowed users to switch to it themselves. 6. `t1.grouping` equals `t2.grouping`, so the change stays inside one group of tariffs. 7. `t2.device` is `tracker`, so the new tariff is one for trackers. 8. The new tariff is available to the user's legal type. See [Tariff (plan)](/docs/navixy-api/user-api/resources/billing/tariff.md). The **effective dealer** is the user's own dealer when its `dealer_id` equals the configured `defaultDealerId`, or when its `dogovor_type` is `paas`. Otherwise it is that dealer's parent. ## API actions API base path: `/tariff/tracker`. Operations that list no errors of their own return only the [general error codes](/docs/navixy-api/general/errors.md#error-codes). *** *Required sub-user rights:* `admin` (available only to master users). ## Change tracker plan > Move a tracker from its current plan to the plan given by \`tariff\_id\`.\ > \ > The change is allowed only when all of the following hold: the tracker belongs to the user and is not a clone; the last change was more than the freeze period ago, 30 days by default; the new plan differs from the current one; both plans belong to the user's effective dealer; the new plan is active; both plans are in the same group; the new plan is for trackers; and the new plan is available to the user's legal type.\ > \ > When the last change was too recent but the current plan has an \`early\_change\_price\`, the change proceeds and that price is charged. Without one it fails with error 240.\ > \ > \*\*Master users only.\*\* A sub-user gets error 13, which the published error list does not mention.\ > \ > Also accepts GET with the same parameters as query-string values.\ > \ > Requires the \`admin\` right. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Billing","description":"Bills, payment systems, subscriptions, device plans and the transaction log. All resources under the /bill/, /payment_system/, /subscription/, /tariff/ and /transaction/ paths."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"responses":{"OK":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true}}}}}},"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/tariff/tracker/change":{"post":{"tags":["Billing"],"summary":"Change tracker plan","description":"Move a tracker from its current plan to the plan given by `tariff_id`.\n\nThe change is allowed only when all of the following hold: the tracker belongs to the user and is not a clone; the last change was more than the freeze period ago, 30 days by default; the new plan differs from the current one; both plans belong to the user's effective dealer; the new plan is active; both plans are in the same group; the new plan is for trackers; and the new plan is available to the user's legal type.\n\nWhen the last change was too recent but the current plan has an `early_change_price`, the change proceeds and that price is charged. Without one it fails with error 240.\n\n**Master users only.** A sub-user gets error 13, which the published error list does not mention.\n\nAlso accepts GET with the same parameters as query-string values.\n\nRequires the `admin` right.","operationId":"tariffTrackerChange","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account. **A blocked tracker is accepted here**, unlike most operations taking a tracker ID.","minimum":1},"tariff_id":{"type":"integer","description":"ID of the new plan.","minimum":1}},"required":["tracker_id","tariff_id"]}}}},"responses":{"200":{"description":"Plan changed","$ref":"#/components/responses/OK"},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 13: the caller is a sub-user. Error 219: the tracker is a clone. Error 221: the new plan's device limit is below the current number of devices. Error 238: the user may not switch this tracker to that plan. Error 240: the plan was last changed 30 days ago or less, and the current plan has no early change price.","$ref":"#/components/responses/ResponseError"},"404":{"description":"Error 239: the new plan does not exist.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` #### Errors These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes): * 201 - Not found in the database - if user doesn't have trackers with given `tracker_id`. * 219 - Not allowed for clones of the device. * 237 - Invalid plan - if there are no plan with specified `tariff_id` and belongs to user's **effective dealer**. * 221 - Device limit exceeded - when new plan limit for devices is less than the current count of devices in the account. * 238 - Changing plan is not allowed - user can't switch tracker to that plan. * 239 - New plan doesn't exist. * 240 - Not allowed changing plan too frequently - plan last changed less or equal to 30 days (**tariff.freeze.period** config option). *** Lists the plans a tracker can switch to, even when the plan was last changed less than **tariff.freeze.period** ago. ## List plans for tracker > List the plans the given tracker can be switched to, together with the wait until the next free change.\ > \ > The list is returned even when the last change was less than the freeze period ago; \`days\_to\_next\_change\` is what tells you whether a change is free yet.\ > \ > Also accepts GET with the same parameters as query-string values. ```json {"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Billing","description":"Bills, payment systems, subscriptions, device plans and the transaction log. All resources under the /bill/, /payment_system/, /subscription/, /tariff/ and /transaction/ paths."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"schemas":{"Plan":{"type":"object","description":"A device plan, called a tariff in older parts of the API.","properties":{"id":{"type":"integer","description":"Unique ID."},"name":{"type":"string","description":"The plan's label."},"group_id":{"type":"integer","description":"Group of plans. A user can only switch to a plan in the same group."},"active":{"type":"boolean","description":"`true` when users may switch to this plan on their own. A user can only switch to an active plan."},"type":{"type":"string","description":"Plan type. The published prose omits `every_year`.","enum":["monthly","everyday","activeday","every_year"]},"price":{"type":"number","description":"Price per month for a `monthly` or `everyday` plan, or price per active day for an `activeday` plan."},"early_change_price":{"type":"number","description":"Price of changing from this plan to another when the last change was less than the freeze period ago, 30 days by default under the `tariff.freeze.period` config option. **Absent when the user may not change plan early**, in which case frequent changes are refused outright."},"device_limit":{"type":"integer","description":"Maximum number of devices per account on this plan."},"has_reports":{"type":"boolean","description":"`true` when reports are allowed."},"paas_free":{"type":"boolean","description":"`true` when this plan is free for the PaaS owner."},"store_period":{"type":"string","description":"Data storage period, such as `2h` for two hours, `3d` for three days, `5m` for five months, or `1y` for one year."},"auto_prolong":{"type":"boolean","description":"Whether the plan renews automatically. Not documented in the published object description."},"features":{"type":"array","description":"Features this plan makes available to the user.","items":{"type":"string","enum":["api","app_tasks","app_fleet","batch_operations","custom_maps","event_notification","geocoding","lbs","map_layers","multilevel_access","priority_support","retranslation","report_xls","report_scheduled","routing","ui_mobile","weblocator","chat","statuses","street_view","driver_journal","checkin","custom_fields","task_route_import"]}},"map_filter":{"type":"object","description":"Which maps the user may use.","properties":{"exclusion":{"type":"boolean","description":"When `true` the maps in `values` are the ones **not** available. When `false` they are the only ones available."},"values":{"type":"array","description":"Map types the filter applies to.","items":{"type":"string"}}}}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/tariff/tracker/list":{"post":{"tags":["Billing"],"summary":"List plans for tracker","description":"List the plans the given tracker can be switched to, together with the wait until the next free change.\n\nThe list is returned even when the last change was less than the freeze period ago; `days_to_next_change` is what tells you whether a change is free yet.\n\nAlso accepts GET with the same parameters as query-string values.","operationId":"tariffTrackerList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tracker_id":{"type":"integer","description":"ID of the tracker, also known as the object ID. Must belong to the current account. **A blocked tracker is accepted here**, unlike most operations taking a tracker ID.","minimum":1}},"required":["tracker_id"]}}}},"responses":{"200":{"description":"Plans available for the tracker","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"list":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}},"days_to_next_change":{"type":"integer","description":"Days until the next free change, or 0 when a free change is available now."}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/navixy-api/user-api/resources/billing/tariff/tariff_tracker.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.