openapi: 3.0.3
info:
  title: Fortnox REST API (Representative Subset) Accounts Invoices API
  description: 'Grounded OpenAPI description of the Fortnox REST API - the Swedish cloud accounting/ERP platform for SMBs and accounting bureaus. Base URL is https://api.fortnox.se/3/. Authentication is OAuth2 Authorization Code Flow: each request carries the Access-Token (Bearer JWT, 1h) header plus the Client-Secret header issued to your Fortnox app. The old fixed Access-Token/Client-Secret integration keys were deprecated 2025-04-30.


    SCOPE / FIDELITY NOTE: The Fortnox API exposes 40+ resources. This document ships a solid, representative SUBSET (Invoices, Customers, Articles, Orders, Offers, Vouchers, Accounts, Financial Years, Suppliers, Supplier Invoices, Projects) with pragmatic, partial field-level schemas. Paths, methods, identifiers, the wrapper-object response envelope (e.g. { "Invoice": {...} }, { "Invoices": [...] }), and auth are grounded in Fortnox''s developer documentation. Per-field property coverage is intentionally partial and MODELED/summarized from the docs, not transcribed field-for-field for every resource. Verify exact field sets and validation against https://api.fortnox.se/apidocs before production use.'
  version: '3.0'
  contact:
    name: Fortnox Developer
    url: https://www.fortnox.se/developer
  license:
    name: Fortnox API License / Terms
    url: https://www.fortnox.se/developer
servers:
- url: https://api.fortnox.se/3
  description: Fortnox REST API v3
security:
- accessToken: []
  clientSecret: []
tags:
- name: Invoices
  description: Accounts-receivable customer invoices.
paths:
  /invoices:
    get:
      operationId: listInvoices
      tags:
      - Invoices
      summary: List invoices
      description: Lists invoices. Supports filtering and pagination via query parameters.
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      - name: filter
        in: query
        description: Predefined filter such as cancelled, fullypaid, unpaid, unpaidoverdue, unbooked.
        schema:
          type: string
      responses:
        '200':
          description: A list of invoices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvoiceListItem'
                  MetaInformation:
                    $ref: '#/components/schemas/MetaInformation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createInvoice
      tags:
      - Invoices
      summary: Create an invoice
      description: Creates a new invoice. The payload is wrapped in an `Invoice` object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Invoice:
                  $ref: '#/components/schemas/Invoice'
      responses:
        '201':
          $ref: '#/components/responses/InvoiceResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /invoices/{DocumentNumber}:
    parameters:
    - $ref: '#/components/parameters/DocumentNumber'
    get:
      operationId: getInvoice
      tags:
      - Invoices
      summary: Retrieve an invoice
      responses:
        '200':
          $ref: '#/components/responses/InvoiceResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateInvoice
      tags:
      - Invoices
      summary: Update an invoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Invoice:
                  $ref: '#/components/schemas/Invoice'
      responses:
        '200':
          $ref: '#/components/responses/InvoiceResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    DocumentNumber:
      name: DocumentNumber
      in: path
      required: true
      description: The document number identifying the invoice/order/offer.
      schema:
        type: string
    page:
      name: page
      in: query
      description: Page number for paginated results.
      schema:
        type: integer
        minimum: 1
    limit:
      name: limit
      in: query
      description: Number of records per page (max 500).
      schema:
        type: integer
        maximum: 500
  schemas:
    ErrorResponse:
      type: object
      description: Fortnox error envelope.
      properties:
        ErrorInformation:
          type: object
          properties:
            Error:
              type: integer
            Message:
              type: string
            Code:
              type: integer
    InvoiceListItem:
      type: object
      properties:
        DocumentNumber:
          type: string
        CustomerNumber:
          type: string
        CustomerName:
          type: string
        InvoiceDate:
          type: string
          format: date
        Total:
          type: number
        Balance:
          type: number
        Currency:
          type: string
    InvoiceRow:
      type: object
      description: A single line item on an invoice, order, or offer.
      properties:
        ArticleNumber:
          type: string
        Description:
          type: string
        DeliveredQuantity:
          type: string
        Price:
          type: number
        VAT:
          type: number
        AccountNumber:
          type: integer
        Unit:
          type: string
    Invoice:
      type: object
      description: Accounts-receivable customer invoice. Partial/modeled field set - see https://api.fortnox.se/apidocs for the full schema.
      properties:
        DocumentNumber:
          type: string
          readOnly: true
        CustomerNumber:
          type: string
        CustomerName:
          type: string
        InvoiceDate:
          type: string
          format: date
        DueDate:
          type: string
          format: date
        Currency:
          type: string
          example: SEK
        Total:
          type: number
        Balance:
          type: number
        Booked:
          type: boolean
        Cancelled:
          type: boolean
        InvoiceRows:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceRow'
      required:
      - CustomerNumber
    MetaInformation:
      type: object
      description: Pagination metadata returned on list endpoints.
      properties:
        '@TotalResources':
          type: integer
        '@TotalPages':
          type: integer
        '@CurrentPage':
          type: integer
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Malformed request or validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid Access-Token / Client-Secret.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InvoiceResponse:
      description: A single invoice.
      content:
        application/json:
          schema:
            type: object
            properties:
              Invoice:
                $ref: '#/components/schemas/Invoice'
    TooManyRequests:
      description: Rate limit exceeded (300 requests/minute per access-token; ~25 per 5s sliding window).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    accessToken:
      type: apiKey
      in: header
      name: Access-Token
      description: OAuth2 Access-Token (Bearer JWT, valid 1 hour) obtained via the Authorization Code Flow from https://apps.fortnox.se/oauth-v1/token. Sent in the Access-Token header on every request.
    clientSecret:
      type: apiKey
      in: header
      name: Client-Secret
      description: The Client-Secret issued to your registered Fortnox developer application. Sent in the Client-Secret header alongside the Access-Token on every request.