Qovery Billing API

openapi: 3.0.0
info:
  version: 1.0.4
  title: Qovery Account Info Billing API
  description: '- Qovery is the fastest way to deploy your full-stack apps on any Cloud provider.

    - ℹ️ The API is stable and still in development.

    '
  contact:
    name: Qovery Product Team
    url: https://www.qovery.com
    email: support+api+documentation@qovery.com
  x-logo:
    url: https://console.qovery.com/assets/logos/logo-white.svg
    altText: Qovery
servers:
- url: https://api.qovery.com
security:
- bearerAuth: []
- ApiKeyAuth: []
tags:
- name: Billing
paths:
  /organization/{organizationId}/currentCost:
    get:
      summary: Get organization current cost
      operationId: getOrganizationCurrentCost
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      responses:
        '200':
          description: Get Cost
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationCurrentCost'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/creditCode:
    post:
      summary: Add credit code
      operationId: addCreditCode
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationCreditCodeRequest'
      responses:
        '200':
          description: add credit code
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/changePlan:
    post:
      summary: Change organization plan
      operationId: changePlan
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationChangePlanRequest'
      responses:
        '200':
          description: plan has been successfully changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/cluster/{clusterId}/currentCost:
    get:
      summary: Get cluster current cost
      operationId: getClusterCurrentCost
      description: 'Get your cluster cost range. We are unable to give a precise cost of your infrastructure at the moment.

        But Qovery guarantees that the cost of your cluster will not exceed the max range.

        '
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/clusterId'
      tags:
      - Billing
      responses:
        '200':
          description: Get cluster cost
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostRange'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/billingInfo:
    get:
      summary: Get organization billing info
      operationId: getOrganizationBillingInfo
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      responses:
        '200':
          description: Get Billing Info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInfo'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    put:
      summary: Edit Organization Billing Info
      operationId: editOrganizationBillingInfo
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingInfoRequest'
      responses:
        '200':
          description: Edit billing info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInfo'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/billingStatus:
    get:
      summary: Get organization billing status
      description: 'This endpoint returns a "is_valid" boolean field reflecting the billing status of the organization:

        - If true, the organization billing is valid

        - For Startup organization, it returns false if there is at least 1 invoice unpaid since 1 week

        - For Community organization, it returns false if there is no credit left

        '
      operationId: getOrganizationBillingStatus
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      responses:
        '200':
          description: Get Billing Status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingStatus'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/billingUsageReport:
    post:
      summary: Generate organization billing usage report
      operationId: generateBillingUsageReport
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationBillingUsageReportRequest'
      responses:
        '200':
          description: billing usage report has been successfully generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationBillingUsageReportResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/billingExternalId:
    get:
      summary: Get organization billing external ID
      description: 'This endpoint returns the external ID of the organization''s billing account

        '
      operationId: getOrganizationBillingExternalId
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      responses:
        '200':
          description: Get Billing External ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingExternalId'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/invoice:
    get:
      summary: List organization invoices
      operationId: listOrganizationInvoice
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      responses:
        '200':
          description: List Invoices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponseList'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/invoice/{invoiceId}:
    get:
      summary: Get organization invoice
      operationId: getOrganizationInvoice
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/invoiceId'
      tags:
      - Billing
      responses:
        '200':
          description: Get Invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/invoice/{invoiceId}/download:
    get:
      summary: Get invoice link
      description: This will return URL of the invoice PDF
      operationId: getOrganizationInvoicePDF
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/invoiceId'
      tags:
      - Billing
      responses:
        '200':
          description: Get invoice PDF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/downloadInvoices:
    post:
      summary: Download all invoices
      operationId: organizationDownloadAllInvoices
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      responses:
        '202':
          description: You will receive an email containing your invoices
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/creditCard:
    get:
      summary: List organization credit cards
      operationId: listOrganizationCreditCards
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      responses:
        '200':
          description: List cfredit cards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditCardResponseList'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    post:
      summary: Add credit card
      operationId: addCreditCard
      parameters:
      - $ref: '#/components/parameters/organizationId'
      tags:
      - Billing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditCardRequest'
      responses:
        '201':
          description: Add credit card
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditCard'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /organization/{organizationId}/creditCard/{creditCardId}:
    delete:
      summary: Delete credit card
      operationId: deleteCreditCard
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/creditCardId'
      tags:
      - Billing
      responses:
        '204':
          $ref: '#/components/responses/204-deletion'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
components:
  schemas:
    BillingInfoRequest:
      type: object
      required:
      - first_name
      - last_name
      - email
      - address
      - zip
      - country_code
      - city
      properties:
        first_name:
          type: string
          example: Forrest
        last_name:
          type: string
          example: Gump
        email:
          type: string
          format: email
          example: forrest@gump.com
          description: email used for billing, and to receive all invoices by email
        address:
          type: string
          example: 21 Jenny Street
        city:
          type: string
          example: Greenbow
        zip:
          type: string
          example: '36744'
        state:
          type: string
          example: Alabama
          description: only for US
        country_code:
          type: string
          description: ISO code of the country
          example: US
        company:
          type: string
          description: name of the company to bill
        vat_number:
          type: string
    InvoiceStatusEnum:
      type: string
      enum:
      - NOT_PAID
      - PAID
      - PAYMENT_DUE
      - PENDING
      - POSTED
      - UNKNOWN
      - VOIDED
    Link:
      type: object
      required:
      - service_id
      - service_type
      - url
      - internal_port
      - external_port
      - is_qovery_domain
      - is_default
      properties:
        service_id:
          type: string
          format: uuid
          description: ID of the associated service
        service_type:
          $ref: '#/components/schemas/ServiceTypeEnum'
        url:
          type: string
          description: URL to access the service
        internal_port:
          type: integer
          description: The port from which the service is reachable from within the cluster
        external_port:
          type: integer
          description: 'The port from which the service is reachable from externally (i.e: 443 for HTTPS)'
        is_qovery_domain:
          type: boolean
          description: True if the domain is managed by Qovery, false if it belongs to the user
        is_default:
          type: boolean
          description: 'Indicate if the link is using the root of the domain and not one derivated from port

            i.e:

            p8080.zxxxx.jvm.worl      => is_default = false, is_qovery = true

            zxxxx.jvm.world           => is_default = true, is_qovery = true

            p8080-my-super-domain.com => is_default = false, is_qovery = false

            my-super-domain.com       => is_default = true, is_qovery = false

            '
    Invoice:
      allOf:
      - $ref: '#/components/schemas/Cost'
      - type: object
        required:
        - id
        - created_at
        - status
        - total_in_cents
        - total
        - currency_code
        properties:
          id:
            type: string
            format: uuid
          created_at:
            type: string
            format: date-time
          status:
            $ref: '#/components/schemas/InvoiceStatusEnum'
    CreditCard:
      type: object
      required:
      - id
      - created_at
      - expiry_month
      - expiry_year
      - last_digit
      - is_expired
      - brand
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        expiry_month:
          type: integer
          example: 6
        expiry_year:
          type: integer
          example: 2025
        last_digit:
          type: string
          example: '7890'
        is_expired:
          type: boolean
        brand:
          type: string
    OrganizationRequest:
      type: object
      required:
      - name
      - plan
      properties:
        name:
          type: string
          description: name is case insensitive
        description:
          type: string
          nullable: true
        plan:
          $ref: '#/components/schemas/PlanEnum'
        website_url:
          type: string
          nullable: true
        repository:
          type: string
          nullable: true
        logo_url:
          type: string
          nullable: true
        icon_url:
          type: string
          nullable: true
        admin_emails:
          type: array
          nullable: true
          items:
            type: string
    BillingInfo:
      type: object
      properties:
        first_name:
          type: string
          example: Forrest
          nullable: true
        last_name:
          type: string
          example: Gump
          nullable: true
        email:
          type: string
          format: email
          example: forrest@gump.com
          description: email used for billing, and to receive all invoices by email
          nullable: true
        address:
          type: string
          example: 21 Jenny Street
          nullable: true
        city:
          type: string
          example: Greenbow
          nullable: true
        zip:
          type: string
          example: '36744'
          nullable: true
        state:
          type: string
          example: Alabama
          description: only for US
          nullable: true
        country_code:
          type: string
          description: ISO code of the country
          example: US
          nullable: true
        company:
          type: string
          description: name of the company to bill
          nullable: true
        vat_number:
          type: string
          nullable: true
    OrganizationCurrentCost:
      allOf:
      - $ref: '#/components/schemas/CurrentCost'
      - type: object
    CurrentCost:
      type: object
      properties:
        plan:
          $ref: '#/components/schemas/PlanEnum'
        remaining_trial_day:
          type: integer
          description: number of days remaining before the end of the trial period
        renewal_at:
          type: string
          description: date when the current plan will be renewed
          readOnly: true
          nullable: true
          format: date-time
        cost:
          $ref: '#/components/schemas/Cost'
    BillingExternalId:
      type: object
      properties:
        id:
          type: string
    ServiceTypeEnum:
      type: string
      x-stoplight:
        id: d66063cd29913
      description: type of the service (application, database, job, ...)
      enum:
      - APPLICATION
      - DATABASE
      - CONTAINER
      - JOB
      - HELM
      - TERRAFORM
      - ARGOCD_APP
    OrganizationBillingUsageReportResponse:
      type: object
      properties:
        report_url:
          description: The URL of the report
          type: string
        delete_report_url:
          description: The URL to delete the report. Use this URL to pro-actively delete the report before it expires
          type: string
    CreditCardResponseList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CreditCard'
    OrganizationCreditCodeRequest:
      type: object
      properties:
        code:
          type: string
    CreditCardRequest:
      type: object
      required:
      - number
      - cvv
      - expiry_month
      - expiry_year
      properties:
        number:
          type: string
        cvv:
          type: string
        expiry_month:
          type: integer
          example: 6
        expiry_year:
          type: integer
          example: 2025
        token:
          type: string
          description: Token generated by payment solution platform.
          nullable: true
    InvoiceResponseList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Invoice'
    CostRange:
      type: object
      required:
      - total_in_cents
      - total
      - currency_code
      properties:
        min_cost_in_cents:
          type: integer
          example: 15000
        min_cost:
          type: number
          example: 150
        max_cost_in_cents:
          type: integer
          example: 30000
        max_cost:
          type: number
          example: 300
        currency_code:
          type: string
          example: USD
    OrganizationChangePlanRequest:
      type: object
      properties:
        plan:
          type: string
    Cost:
      type: object
      required:
      - total_in_cents
      - total
      - currency_code
      properties:
        total_in_cents:
          type: integer
          example: 30000
        total:
          type: number
          example: 300
        currency_code:
          type: string
          example: USD
    PlanEnum:
      type: string
      description: FREE, BUSINESS & PROFESSIONAL are deprecated. 2025 plans are the new plans available.
      enum:
      - FREE
      - TEAM
      - TEAM_YEARLY
      - ENTERPRISE
      - ENTERPRISE_YEARLY
      - PROFESSIONAL
      - BUSINESS
      - USER_2025
      - TEAM_2025
      - BUSINESS_2025
      - ENTERPRISE_2025
    BillingStatus:
      type: object
      properties:
        is_valid:
          type: boolean
        message:
          type: string
    OrganizationBillingUsageReportRequest:
      type: object
      required:
      - from
      - to
      - report_expiration_in_seconds
      properties:
        from:
          description: The start date of the report
          type: string
          format: date-time
          example: '2020-01-01T00:00:00.000Z'
        to:
          description: The end date of the report
          type: string
          format: date-time
          example: '2020-01-31T23:59:59.000Z'
        report_expiration_in_seconds:
          description: The number of seconds the report will be publicly available
          type: integer
          example: 3600
    Base:
      type: object
      required:
      - id
      - created_at
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        created_at:
          type: string
          readOnly: true
          format: date-time
        updated_at:
          type: string
          readOnly: true
          format: date-time
    Organization:
      allOf:
      - $ref: '#/components/schemas/Base'
      - $ref: '#/components/schemas/OrganizationRequest'
      - type: object
        properties:
          owner:
            type: string
            format: uuid
            description: uuid of the user owning the organization
          billing_deployment_restriction:
            type: string
            nullable: true
            description: If set, indicates a billing-related restriction on the organization. 'NO_CREDIT_CARD' means the organization is on a free trial without a credit card — managed cluster creation and deployments on managed clusters are blocked, but demo cluster usage is allowed. Any other value blocks all deployments. null means no restriction.
      - type: object
        properties:
          organization_plan:
            type: object
            properties:
              plan:
                $ref: '#/components/schemas/PlanEnum'
              audit_logs_retention_in_days:
                type: number
                description: audit logs maximum period available in days
  responses:
    '400':
      description: Bad request
    204-deletion:
      description: The resource was deleted successfully
    '403':
      description: Access forbidden
    '404':
      description: Resource not found
    '401':
      description: Access token is missing or invalid
  parameters:
    invoiceId:
      name: invoiceId
      in: path
      description: Invoice ID
      required: true
      schema:
        type: string
        format: uuid
    clusterId:
      name: clusterId
      in: path
      description: Cluster ID
      required: true
      schema:
        type: string
        format: uuid
    organizationId:
      name: organizationId
      in: path
      description: Organization ID
      required: true
      schema:
        type: string
        format: uuid
    creditCardId:
      name: creditCardId
      in: path
      description: Credit Card ID
      required: true
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT tokens should be used with OIDC account (human to machine). JWT tokens used by the Qovery console to communicate with the API have a TTL. Curl Example '' curl https://console.qovery.com/organization -H "Authorization: Bearer $qovery_token" '''
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Token API are generated by Qovery to manage machine to machine interaction and do not have a TTL. Curl Example '' curl https://console.qovery.com/organization -H "Authorization: Token $qovery_token" '''
x-tagGroups:
- name: Organization
  tags:
  - Organization Main Calls
  - Organization Api Token
  - Organization Account Git Repositories
  - Organization Cluster Lock
  - Organization Webhook
  - Organization Custom Role
  - Organization Event
  - Organization Annotations Group
  - Organization Labels Group
  - Organization Enterprise Connection
  - Projects
  - Members
  - Billing
  - Clusters
  - Cloud Provider
  - Cloud Provider Credentials
  - Github App
  - Container Registries
  - Helm Repositories
- name: Project
  tags:
  - Project Main Calls
  - Environments
  - Project Deployment Rule
  - Project Environment Variable
  - Project Secret
- name: Environment
  tags:
  - Environment Main Calls
  - Applications
  - Containers
  - Databases
  - Jobs
  - Helms
  - Terraforms
  - Environment Actions
  - Environment Logs
  - Environment Deployment History
  - Environment Deployment Rule
  - Environment Variable
  - Environment Secret
  - Environment Export
- name: Deployment Stage
  tags:
  - Deployment Stage Main Calls
- name: Application
  tags:
  - Application Main Calls
  - Application Actions
  - Application Configuration
  - Application Custom Domain
  - Application Database
  - Application Logs
  - Application Deployment Restriction
  - Application Deployment History
  - Application Environment Variable
  - Application Secret
  - Application Annotations Group
- name: Container
  tags:
  - Container Main Calls
  - Container Actions
  - Container Configuration
  - Container Custom Domain
  - Container Database
  - Container Logs
  - Container Deployment History
  - Container Environment Variable
  - Container Secret
  - Container Annotations Group
- name: Database
  tags:
  - Database Main Calls
  - Database Actions
  - Database Applications
  - Database Deployment History
  - Database Containers
  - Database Application
  - Database Container
  - Backups
  - Database Annotations Group
- name: Job
  tags:
  - Job Main Calls
  - Job Actions
  - Job Configuration
  - Job Custom Domain
  - Job Deployment Restriction
  - Job Deployment History
  - Job Environment Variable
  - Job Secret
  - Job Annotations Group
- name: Helm
  tags:
  - Helm Main Calls
  - Helm Actions
  - Helm Configuration
  - Helm Custom Domain
  - Helm Deployment Restriction
  - Helm Deployment History
- name: Terraform
  tags:
  - Terraform Main Calls
  - Terraform Actions
  - Terraform Configuration
  - Terraform Deployment Restriction
  - Terraform Deployment History
- name: Account
  tags:
  - Account Info
  - Git repositories
  - Referral & Rewards
- name: Git
  tags:
  - Git repositories
- name: Variable
  tags:
  - Variable Main Calls
- name: Lifecycle Template
  tags:
  - Lifecycle Template Main Calls
- name: Admin
  tags:
  - User Sign Up
- name: Alerting
  tags:
  - Alert Receivers
  - Alert Rules