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

# Create a commission plan

> **Beta. This endpoint is unstable and may still change without notice.** Pin against the dated version and watch the changelog.

Create a commission plan. Both monthly thresholds are optional and are evaluated per sales rep, per plan, per calendar month.



## OpenAPI

````yaml assets/openapi-v2-commission.json post /api/commissions/plans
openapi: 3.1.0
info:
  title: Fynn V2 Commission API
  version: 2026-07
  description: >-
    REST API for Fynn commission plans. Define how sales reps earn commission on
    invoices, set per-product rates, and control two monthly payout gates: a
    minimum payout and a minimum monthly revenue, each evaluated per sales rep
    and calendar month. Authenticate with a bearer token of your Organisation
    that carries the commission-plans permission.
servers:
  - url: https://coreapi.io
    description: Production
  - url: https://preview.coreapi.io
    description: Sandbox
security:
  - BearerToken: []
tags:
  - name: Commission Plans
    description: >-
      Create and manage commission plans, rates, product rules and monthly
      payout gates.
paths:
  /api/commissions/plans:
    post:
      tags:
        - Commission Plans
      summary: Create a commission plan
      description: >-
        **Beta. This endpoint is unstable and may still change without notice.**
        Pin against the dated version and watch the changelog.


        Create a commission plan. Both monthly thresholds are optional and are
        evaluated per sales rep, per plan, per calendar month.
      operationId: createCommissionPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommissionPlanInput'
      responses:
        '201':
          description: The created commission plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommissionPlan'
        '400':
          description: The request body is invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemError'
        '401':
          description: Authentication is missing or the token is invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemError'
        '403':
          description: The token lacks the permission to manage commission plans.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemError'
        '422':
          description: The request body failed validation.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationError'
components:
  schemas:
    CommissionPlanInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 255
          description: Internal name of the plan.
        type:
          type: string
          enum:
            - ongoing_percentage
          default: ongoing_percentage
          description: How the commission is calculated.
        percentage:
          type: string
          nullable: true
          example: '0.10'
          description: Base commission rate as a decimal fraction (0.10 = 10 %).
        basisType:
          type: string
          enum:
            - net
            - gross
          nullable: true
          description: Whether the commission is based on the net or gross invoice amount.
        triggerEvent:
          type: string
          enum:
            - invoice_finalized
            - invoice_paid
          default: invoice_finalized
          description: When the commission is calculated.
        commissionScope:
          type: string
          enum:
            - all_invoices
            - first_contract_period
          default: all_invoices
          description: Which invoices generate commission.
        requireDeal:
          type: boolean
          default: false
          description: When true, only invoices linked to a deal generate commission.
        payoutThresholdAmount:
          type: object
          description: >-
            Minimum commission a sales rep must accumulate on this plan within a
            calendar month for that month's commissions to be paid out.
            Evaluated per sales rep, per plan, per month. Null means no minimum.
          required:
            - amount
          properties:
            amount:
              type: integer
              description: Amount in the currency's minor unit (e.g. cents).
            currency:
              type: string
              default: EUR
              description: ISO 4217 currency code.
            precision:
              type: integer
              default: 2
              description: Number of minor-unit decimals.
          nullable: true
        monthlyRevenueThreshold:
          type: object
          description: >-
            Minimum invoice revenue a sales rep must generate on this plan
            within a calendar month before any commission for that month is paid
            out. If the revenue stays below this, the whole month is withheld.
            Evaluated per sales rep, per plan, per month. Null means no minimum.
          required:
            - amount
          properties:
            amount:
              type: integer
              description: Amount in the currency's minor unit (e.g. cents).
            currency:
              type: string
              default: EUR
              description: ISO 4217 currency code.
            precision:
              type: integer
              default: 2
              description: Number of minor-unit decimals.
          nullable: true
        rules:
          type: array
          items:
            $ref: '#/components/schemas/CommissionPlanRuleInput'
    CommissionPlan:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        percentage:
          type: string
          nullable: true
          description: Base commission rate as a decimal fraction.
        basisType:
          type: string
          nullable: true
        triggerEvent:
          type: string
        commissionScope:
          type: string
        requireDeal:
          type: boolean
        payoutThresholdAmount:
          type: object
          properties:
            amount:
              type: integer
              description: Amount in the currency's minor unit (e.g. cents).
            displayAmount:
              type: number
              description: The amount as a decimal, for display.
            currency:
              type: string
              description: ISO 4217 currency code.
            precision:
              type: integer
              description: Number of minor-unit decimals.
          nullable: true
          description: >-
            Minimum commission a sales rep must accumulate on this plan within a
            calendar month for that month's commissions to be paid out.
            Evaluated per sales rep, per plan, per month. Null means no minimum.
        monthlyRevenueThreshold:
          type: object
          properties:
            amount:
              type: integer
              description: Amount in the currency's minor unit (e.g. cents).
            displayAmount:
              type: number
              description: The amount as a decimal, for display.
            currency:
              type: string
              description: ISO 4217 currency code.
            precision:
              type: integer
              description: Number of minor-unit decimals.
          nullable: true
          description: >-
            Minimum invoice revenue a sales rep must generate on this plan
            within a calendar month before any commission for that month is paid
            out. If the revenue stays below this, the whole month is withheld.
            Evaluated per sales rep, per plan, per month. Null means no minimum.
        isActive:
          type: boolean
        rules:
          type: array
          items:
            $ref: '#/components/schemas/CommissionPlanRule'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ProblemError:
      type: object
      description: >-
        Problem detail error body (application/problem+json). Additional members
        may be present depending on the error.
      properties:
        status:
          type: integer
          example: 404
        type:
          type: string
          description: Stable machine readable error key.
          example: PLAN__NOT_FOUND
        title:
          type: string
          example: An error occurred
        detail:
          type: string
          example: Plan not found.
      required:
        - status
        - type
        - title
        - detail
    ValidationError:
      type: object
      description: >-
        Validation error body (application/problem+json) returned when input
        fails field level validation.
      properties:
        status:
          type: integer
          example: 422
        type:
          type: string
          example: https://tools.ietf.org/html/rfc2616#section-10
        title:
          type: string
          example: Validation Failed
        violations:
          type: array
          items:
            type: object
            properties:
              propertyPath:
                type: string
                example: tiers[0].name
              message:
                type: string
                example: This value should not be blank.
              code:
                type: string
                nullable: true
      required:
        - status
        - type
        - title
        - violations
    CommissionPlanRuleInput:
      type: object
      description: Overrides the base percentage for a specific product.
      properties:
        productId:
          type: string
          format: uuid
          nullable: true
          description: Fynn product this rule applies to.
        externalProductReference:
          type: string
          maxLength: 255
          nullable: true
          description: >-
            External product reference this rule applies to, when the product
            lives in a connected system.
        percentage:
          type: string
          example: '0.20'
          description: Commission rate as a decimal fraction (0.20 = 20 %).
        priority:
          type: integer
          default: 0
          description: Higher priority wins when several rules match.
    CommissionPlanRule:
      type: object
      properties:
        id:
          type: string
        productId:
          type: string
          nullable: true
        externalProductReference:
          type: string
          nullable: true
        percentage:
          type: string
          description: Commission rate as a decimal fraction (0.20 = 20 %).
        priority:
          type: integer
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      description: >-
        Bearer token of your Organisation with the commission-plans permission
        (read for GET, write for POST/PUT/DELETE). Send it as Authorization:
        Bearer <token>.

````