InfraNest Billing API

openapi: 3.2.0
info:
  title: InfraNest Billing API
  description: Domains, DNS, cloud servers, certificates and uptime monitoring in one API, across the registrars, DNS hosts and clouds you already use, such as Cloudflare, Route 53, Hetzner and GoDaddy. Start in a free sandbox with sample data, use scoped tokens, try DNS changes as a dry run first, and retry safely with idempotency keys.
  version: 1.0.0
  x-logo:
    url: https://developers.infranest.io/logo.svg
    altText: InfraNest
  contact:
    name: InfraNest
    url: https://developers.infranest.io
  termsOfService: https://infranest.io/terms
servers:
- url: https://api.infranest.io
security:
- default: []
tags:
- name: Billing
  description: ''
paths:
  /api/organizations/{organization_id}/subscription:
    get:
      summary: Get the subscription
      operationId: getApiOrganizationsOrganization_idSubscription
      description: The organization’s subscription and plan, the plan whose limits currently apply, whether a free trial is still available and any discount in force. Read-only; returns 404 when there is no subscription.
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                id: 1
                organization_id: 1
                plan_id: 2
                status: active
                provider: stripe
                provider_subscription_id: sub_demo_northwind
                trial_ends_at: null
                current_period_start: '2026-01-01T00:00:00.000000Z'
                current_period_end: '2026-02-15T12:00:00.000000Z'
                canceled_at: null
                created_at: '2026-01-15T12:00:00.000000Z'
                updated_at: '2026-01-15T12:00:00.000000Z'
                cancel_at_period_end: false
                stripe_price_id: null
                currency: eur
                trial_reminder_sent_at: null
                renewal_reminder_sent_at: null
                card_expiry_reminder_sent_at: null
                addons: []
                card_on_file: false
                trial_recap_sent_at: null
                trial_last_call_sent_at: null
                trial_first_steps_sent_at: null
                trial_ended_at: null
                trial_reactivation_sent_at: null
                recap_period_start: null
                renewal_recap_sent_for: null
                discount_code: null
                discount_percent: null
                discount_amount_off: null
                discount_duration: null
                discount_starts_at: null
                discount_ends_at: null
                discount_label: null
                grace_reminder_sent_at: null
                stay_offer_used_at: null
                paused_until: null
                pause_used_at: null
                pause_limits: null
                pause_reminder_sent_at: null
                pending_plan_id: null
                pending_cadence: null
                pending_change_at: null
                stripe_schedule_id: null
                collection_method: null
                plan:
                  id: 2
                  name: Pro
                  slug: pro
                  description: For freelancers & solo devs — faster checks, cloud, API and automations.
                  limits:
                    api: true
                    rate:
                      manual_sync_per_hour: 30
                      domain_checks_per_hour: 100
                      monitor_checks_per_hour: 120
                      provider_api_per_minute: 300
                    cloud: true
                    api.mcp: true
                    domains: 100
                    servers: 10
                    api.read: true
                    monitors: 50
                    webhooks: true
                    api.write: true
                    dns.drift: true
                    dns_zones: 100
                    drop_catch: true
                    automations: 25
                    data_import: true
                    dynamic_ips: 10
                    certificates: 100
                    status_pages: 3
                    team_members: 3
                    cloud.backups: true
                    cloud.volumes: true
                    dns.templates: true
                    organizations: 1
                    api.tokens_max: 5
                    cloud.firewalls: true
                    cloud.snapshots: true
                    watched_domains: 50
                    cloud.volumes_max: 10
                    external_monitors: 5
                    dropcatch.register: true
                    cloud.firewalls_max: 5
                    audit.retention_days: 30
                    domains.registration: true
                    monitor_min_interval: 60
                    monitoring.incidents: true
                    reputation.check_days: 7
                    monitoring.maintenance: true
                    cloud.load_balancers_max: 0
                    monitoring.calendar_feed: true
                    monitoring.retention_days: 90
                    monitoring.uptime_targets: true
                    status_page_custom_domain: true
                    dns.history_retention_days: 90
                    automations.automatic_fixes: true
                    automations.premium_actions: true
                    integrations.connections_max: 5
                  price_monthly: 2250
                  price_yearly: 22800
                  active: true
                  created_at: '2026-01-15T12:00:00.000000Z'
                  updated_at: '2026-01-15T12:00:00.000000Z'
                  is_public: true
                  sort_order: 2
                  stripe_product_id: null
                  stripe_prices: null
                  prices:
                    eur:
                      yearly: 22800
                      monthly: 2250
                  trial_days: 0
                  recommended: false
                  name_i18n: null
                  description_i18n: null
                  badge: null
                  tagline_i18n:
                    de: Freelancer & Solo-Entwickler
                    en: Freelancers & solo devs
                    fr: Freelances & développeurs solo
                    nl: Freelancers & solo-ontwikkelaars
                  highlights_i18n:
                    de:
                    - Alles in Free
                    - 100 Domains
                    en:
                    - Everything in Free
                    - 100 domains
                    fr:
                    - Tout dans Free
                    - 100 domaines
                    nl:
                    - Alles in Free
                    - 100 domeinen
                  contact_sales: false
                  contact_url: null
                effective_plan_id: 2
                effective_plan_slug: pro
                plan_source: subscription
                inherited_from: null
                covers: []
                promotion_eligible: false
                trial_available: false
                referral_welcome: null
                suggested_promotion_code: null
                discount: null
                fitting_plan_id: 3
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Billing
      x-infranest-scope: billing.read
      x-infranest-token-writable: false
      x-infranest-module: billing
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/subscription/impact:
    get:
      summary: Preview what a plan change would lock
      operationId: gETsubscriptionimpactWhatAPlanChangeWouldLockRefuseOrTurnOffBeforeItIsConfirmed3585
      description: 'What changes for this organization if it moves to another plan: the items over a limit that would be locked (with the first few named), the counts that stay but cannot grow, monitors that would check less often, and the features it would lose. Pass `plan_id` for a plan change, or leave it out to preview where the organization lands when its subscription ends. `lines` words the same changes in `locale` (en, nl, de or fr). Read-only; empty when nothing changes.'
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                rows:
                - type: interval
                  count: 1
                  seconds: 300
                lines:
                - 1 monitor checks every 5 minutes instead of at its own faster interval.
                groups:
                  stops:
                  - 1 monitor checks every 5 minutes instead of at its own faster interval.
                  keeps: null
                  features: null
                locks_on: null
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Billing
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                plan_id:
                  type:
                  - integer
                  - 'null'
                  description: ''
                  example: 16
                locale:
                  type:
                  - string
                  - 'null'
                  description: ''
                  example: en
                  enum:
                  - en
                  - nl
                  - de
                  - fr
                  - null
      x-infranest-scope: billing.read
      x-infranest-token-writable: false
      x-infranest-module: billing
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/subscription/addons:
    get:
      summary: List add-ons
      operationId: gETsubscriptionaddonsPublicAddOnsWithPrices+WhichAreActiveForThisOrg177
      description: The add-ons on offer with their prices, each marked `owned` when the organization already has it. Read-only.
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              example: []
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Billing
      x-infranest-scope: billing.read
      x-infranest-token-writable: false
      x-infranest-module: billing
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/subscription/insights:
    get:
      summary: Read what the plan page knows about this organization
      operationId: gETsubscriptioninsightsWhatThePlanPageKnowsAboutThisWorkspace55615562TheMonthsReceiptEvidenceFromItsOwnHistoryWhatEachPlanWouldMeanForWhatItHasAGrowthForecastAndWhatItsTeamAskedForReadOnlyTenMinutesPerWorkspaceAndLanguageBecauseTheReceiptIsAMonthOfRecap
      description: 'Facts specific to this organization, for choosing a plan: `receipt` (what InfraNest did for it in the last 30 days, when it pays), `evidence` (up to two lines from its own history that a bigger plan would have changed; empty while a critical problem is open), `plans` (per plan id: whether everything fits, and if not how many items would lock and the first of them), `forecast` (counts growing steadily toward the current limit, with the weeks left) and `asked` (entitlement keys members asked for in the last 90 days). Worded in `locale` (en, nl, de or fr). Read-only; cached for ten minutes.'
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                receipt:
                - title: 6 outages caught and alerted
                  detail: ''
                  url: http://localhost/monitoring/incidents
                - title: 103,680 checks run across your 13 monitors
                  detail: ''
                  url: http://localhost/monitoring
                evidence: []
                plans:
                  '1':
                    fits: true
                    locks: 0
                    first: null
                  '3':
                    fits: true
                    locks: 0
                    first: null
                forecast: []
                asked: []
                tried: []
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Billing
      x-infranest-scope: billing.read
      x-infranest-token-writable: false
      x-infranest-module: billing
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/invoices:
    get:
      summary: List invoices
      operationId: gETinvoicesTheOrgsInvoicesbackfilledFromStripeSoHistoryShows
      description: Your most recent 100 invoices, newest first, with their status, totals, billing period and links to view or download each one. Read-only.
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
              - id: 6
                number: INF-2026-0100
                status: paid
                currency: eur
                total: 4719
                tax: 819
                paid_at: '2026-01-02T00:00:00.000000Z'
                hosted_invoice_url: null
                invoice_pdf: null
                period_start: '2026-01-01T00:00:00.000000Z'
                period_end: '2026-01-31T23:59:59.000000Z'
                created_at: '2026-01-01T00:00:00.000000Z'
              - id: 5
                number: INF-2025-0101
                status: paid
                currency: eur
                total: 4719
                tax: 819
                paid_at: '2025-12-02T00:00:00.000000Z'
                hosted_invoice_url: null
                invoice_pdf: null
                period_start: '2025-12-01T00:00:00.000000Z'
                period_end: '2025-12-31T23:59:59.000000Z'
                created_at: '2025-12-01T00:00:00.000000Z'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Billing
      x-infranest-scope: billing.read
      x-infranest-token-writable: false
      x-infranest-module: billing
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/credit-notes:
    get:
      summary: List credit notes
      operationId: gETcreditNotesTheReversingHalfOfTheOrgsBillingHistory642
      description: Credit notes issued against your invoices, with the invoice each one credits, its amounts (negative, in the currency’s smallest unit), how it was settled and a PDF link. Read-only.
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              example: []
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Billing
      x-infranest-scope: billing.read
      x-infranest-token-writable: false
      x-infranest-module: billing
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/account-credit:
    get:
      summary: Get account credit
      operationId: gETaccountCreditMoneyWeOweThemPerCurrency662
      description: Money InfraNest holds for you — for example after a downgrade or a refund — which comes off your next invoice. One balance per currency, in the currency’s smallest unit; empty when you have none. Read-only.
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                credit: []
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Billing
      x-infranest-scope: billing.read
      x-infranest-token-writable: false
      x-infranest-module: billing
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
components:
  responses:
    Error401:
      description: The token is missing, wrong, expired or revoked. The body is an Error; its `code` says which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error404:
      description: Nothing exists at this address, or you cannot see it. The body is an Error; its `code` says which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error429:
      description: 'Too many requests: wait the seconds in Retry-After. The body is an Error; its `code` says which.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error403:
      description: The token or your role may not do this here. The body is an Error; its `code` says which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - code
      - message
      - hint
      - retryable
      properties:
        code:
          type: string
          enum:
          - unauthenticated
          - scope_missing
          - session_only
          - not_token_writable
          - write_disabled
          - wrong_organization
          - token_ip_not_allowed
          - test_token_required
          - test_token_sandbox_only
          - api_token_required
          - sandbox_personal
          - sandbox_needs_organization
          - organization_offline
          - permission_denied
          - forbidden
          - organization_suspended
          - read_only_session
          - sso_required
          - two_factor_setup_required
          - password_reset_required
          - email_verification_required
          - plan_limit
          - not_found
          - method_not_allowed
          - conflict
          - validation_failed
          - unprocessable
          - range_too_large
          - rate_limited
          - idempotency_key_reused
          - idempotency_in_progress
          - provider_refused
          - provider_rate_limited
          - provider_unavailable
          - maintenance
          - server_error
          description: 'What kind of error this is. Stable: codes are added, never renamed or removed.'
        message:
          type: string
          description: A sentence for people. May be reworded.
        hint:
          type: string
          description: What to do about it.
        retryable:
          type: boolean
          description: Whether the same request can succeed later unchanged.
        docs_url:
          type: string
          format: uri
        reference:
          type: string
          description: The request ID; also the X-Request-Id header.
        retry_after:
          type: integer
          description: Seconds to wait before retrying.
        required:
          type: string
          description: The missing token scope (scope_missing).
        required_permission:
          type: string
          description: The missing role permission (permission_denied).
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: Create a token in the app under My account → Developer. Tokens are managed in the app only, never through the API.
externalDocs:
  description: 'InfraNest: domains, DNS, cloud servers, certificates and uptime monitoring in one place'
  url: https://infranest.io