> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dezerx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List upgrade options

> Products the service can be upgraded to with the prorated cost. Empty when upgrades are disabled, the service is not active, is overdue or its module does not support plan changes.

**Permission:** `services.upgrades.read`



## OpenAPI

````yaml /docs/service-api.yaml get /services/{service}/upgrade-options
openapi: 3.1.0
info:
  title: Spartan Service API
  version: '2026.11'
  description: >-
    Services: create, read and update, lifecycle actions, billing and pricing,
    plan changes, notes, members, addons, provider details and dispute evidence.


    All requests need an API key from **Admin, API** in the `Authorization:
    Bearer <key>` header. Replace `{domain}` with the domain of your Spartan
    installation. Successful responses use the envelope `{"data": ..., "meta":
    {"request_id": ...}}`; errors use `{"error": {"code", "message", "details"},
    "request_id"}`.
servers:
  - url: https://{domain}/api/application
    description: Your Spartan installation
    variables:
      domain:
        default: billing.example.com
        description: Domain of your Spartan installation, without https://
security:
  - bearerAuth: []
tags:
  - name: Services
  - name: Lifecycle
  - name: Billing
  - name: Upgrades
  - name: Notes
  - name: Members
  - name: Addons
  - name: Service details
  - name: Evidence
paths:
  /services/{service}/upgrade-options:
    get:
      tags:
        - Upgrades
      summary: List upgrade options
      description: >-
        Products the service can be upgraded to with the prorated cost. Empty
        when upgrades are disabled, the service is not active, is overdue or its
        module does not support plan changes.


        **Permission:** `services.upgrades.read`
      operationId: listUpgradeOptions
      parameters:
        - name: service
          in: path
          required: true
          description: Service id.
          schema:
            type: integer
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UpgradeOption'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - data
                  - meta
              example:
                data:
                  - id: 20
                    name: Minecraft Advanced
                    description: >-
                      <ul style="margin-top:16px; line-height:2;
                      list-style:none; padding:0;">
                          <li>✅ <strong>8 GB RAM</strong></li>
                          <li>✅ <strong>16 GB NVMe storage</strong></li>
                          <li>✅ backups &amp; DDoS protection</li>
                          <li>✅ One click plugin &amp; mod installer</li>
                          <li>✅ 24/7 support</li>
                      </ul>
                    image: products/gGPRQ6sy9Gzr0JDaUz2aaA8OIE6Tmp1sKsXNoprX.png
                    icon_image: null
                    price: 25
                    upgrade_cost: 24
                    cost_breakdown:
                      current_price: 1
                      new_price: 25
                      upgrade_fee: 0
                      prorated_current: 1
                      prorated_new: 25
                      difference: 24
                      days_remaining: 19.999996
                      actual_days_remaining: 19.999996
                      total_days: 30
                      prorate: false
                meta:
                  request_id: 5dd15885-a15c-4098-9b2b-1a3149c2aa83
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    UpgradeOption:
      type: object
      properties:
        id:
          type: integer
          description: Target product id. Send it as `new_product_id`.
        name:
          type: string
        description:
          type:
            - string
            - 'null'
          description: Product description (HTML).
        image:
          type:
            - string
            - 'null'
        icon_image:
          type:
            - string
            - 'null'
        price:
          type: number
          description: Price of the target product for the service billing cycle.
        upgrade_cost:
          type: number
          description: Amount the upgrade invoice will be issued for.
        cost_breakdown:
          $ref: '#/components/schemas/CostBreakdown'
    Meta:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
          description: Request id, also sent in the `X-Request-ID` response header.
      required:
        - request_id
    CostBreakdown:
      type: object
      properties:
        current_price:
          type: number
        new_price:
          type: number
        upgrade_fee:
          type: number
          description: Upgrade only.
        downgrade_fee:
          type: number
          description: Downgrade only.
        prorated_current:
          type: number
        prorated_new:
          type: number
        difference:
          type: number
          description: Amount that will be invoiced.
        days_remaining:
          type: number
        actual_days_remaining:
          type: number
        total_days:
          type: integer
        prorate:
          type: boolean
          description: Upgrade only.
        is_refund:
          type: boolean
          description: Downgrade only.
        refund_amount:
          type: number
          description: Downgrade only.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Machine readable error code, for example `unauthorized`,
                `forbidden`, `not_found`, `invalid_service_state`.
            message:
              type: string
              description: Human readable explanation.
            details:
              type: object
              properties: {}
              description: Extra context. An empty object for most errors.
              additionalProperties: true
          required:
            - code
            - message
            - details
        request_id:
          type: string
          format: uuid
          description: >-
            Request id. Also returned in the `X-Request-ID` header. Send your
            own with `X-Request-ID` to correlate logs.
      description: Error envelope returned by every failed request.
      required:
        - error
        - request_id
  responses:
    Unauthorized:
      description: Missing, invalid or inactive API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: No Authorization header
              value:
                error:
                  code: unauthorized
                  message: Bearer token required.
                  details: {}
                request_id: 9aca26ca-e06f-4725-8e4b-4385d6c03422
            invalid:
              summary: Unknown or inactive key
              value:
                error:
                  code: unauthorized
                  message: Invalid or inactive token.
                  details: {}
                request_id: 8802a669-6f06-453e-a1d8-0b81621167c3
    Forbidden:
      description: >-
        The key lacks the permission for this endpoint, or the request IP is not
        in the key allow list.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              summary: Missing permission
              value:
                error:
                  code: forbidden
                  message: Insufficient permissions for this action.
                  details: {}
                request_id: 191c51e1-03a3-448e-8df7-3c584be888b0
            ip_not_allowed:
              summary: IP not allowed
              value:
                error:
                  code: ip_not_allowed
                  message: Access denied from this IP address.
                  details: {}
                request_id: 3f6c2a1e-8b4d-4f7a-9c2e-5d1b7a9e0c42
    NotFound:
      description: The resource in the path does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: The requested resource was not found.
              details: {}
            request_id: cccbc627-4fd4-4727-889e-fa727c48792c
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key created in Admin, API. Send it as `Authorization: Bearer <key>`.
        Each key has its own permissions and optional IP allow list.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.