Create a commission rule

curl --request POST \
  --url https://api.journeybee.io/v1/commissions/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "<string>",
  "tier_uuids": [
    "<string>"
  ],
  "category_uuids": [
    "<string>"
  ],
  "partnership_uuids": [
    "<string>"
  ]
}
'

{
  "uuid": "<string>",
  "label": "<string>",
  "payment_target": "<string>",
  "auto_assign_recipient": "<string>",
  "calculation": {
    "entries": [
      {
        "payment_stage_id": 123,
        "calculation": {
          "value": "<string>",
          "scalingConfig": {
            "customFieldId": 123,
            "tiers": [
              {
                "optionId": 123,
                "value": 123
              }
            ]
          },
          "number_of_occurrences": 123,
          "periodRates": {
            "enabled": true,
            "periods": [
              {
                "periodNumber": 123,
                "startOccurrence": 123,
                "endOccurrence": 123,
                "value": 123,
                "scalingConfig": {
                  "customFieldId": 123,
                  "tiers": [
                    {
                      "optionId": 123,
                      "value": 123
                    }
                  ]
                }
              }
            ]
          },
          "split": {
            "oneOff": {
              "value": "<string>",
              "scalingConfig": {
                "customFieldId": 123,
                "tiers": [
                  {
                    "optionId": 123,
                    "value": 123
                  }
                ]
              },
              "number_of_occurrences": 123,
              "periodRates": {
                "enabled": true,
                "periods": [
                  {
                    "periodNumber": 123,
                    "startOccurrence": 123,
                    "endOccurrence": 123,
                    "value": 123,
                    "scalingConfig": {
                      "customFieldId": 123,
                      "tiers": [
                        {
                          "optionId": 123,
                          "value": 123
                        }
                      ]
                    }
                  }
                ]
              }
            },
            "recurring": {
              "value": "<string>",
              "scalingConfig": {
                "customFieldId": 123,
                "tiers": [
                  {
                    "optionId": 123,
                    "value": 123
                  }
                ]
              },
              "number_of_occurrences": 123,
              "periodRates": {
                "enabled": true,
                "periods": [
                  {
                    "periodNumber": 123,
                    "startOccurrence": 123,
                    "endOccurrence": 123,
                    "value": 123,
                    "scalingConfig": {
                      "customFieldId": 123,
                      "tiers": [
                        {
                          "optionId": 123,
                          "value": 123
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        }
      }
    ]
  },
  "tiers": [
    {
      "uuid": "<string>",
      "label": "<string>"
    }
  ],
  "categories": [
    {
      "uuid": "<string>",
      "label": "<string>"
    }
  ],
  "partnerships": [
    {
      "uuid": "<string>",
      "name": "<string>"
    }
  ],
  "created_at": "<string>",
  "updated_at": "<string>"
}

Commissions

Create a commission rule

Create a commission rule with calculation entries. Optionally scope to specific tiers, categories, or partnerships via their UUIDs.

Calculation structure

The calculation object contains entries — an array of payment triggers:

{
  "entries": [
    {
      "payment_stage_id": 123,
      "calculation": {
        "type": "oneOff",
        "option": "percentage",
        "value": 10
      }
    }
  ]
}

Calculation types

oneOff: Single payment when stage is reached. option: fixed (flat amount), percentage (of deal value), or scaling (varies by custom field).
recurring: Multiple payments over time. Additional fields: recurring_period (weekly/monthly/quarterly/yearly), number_of_occurrences. Supports periodRates for variable rates per period.
split: Different calculations for one-off and recurring components. Contains split.oneOff and split.recurring sub-calculations.

Scaling

When option is scaling, provide scalingConfig with customFieldId and tiers array mapping custom field option IDs to fixed/percentage values.

Scoping

Commissions can be scoped to apply only to specific partners:

tier_uuids — apply to partners in these tiers
category_uuids — apply to partners in these categories
partnership_uuids — apply to these specific partnerships (highest priority)

POST

commissions

Create a commission rule

curl --request POST \
  --url https://api.journeybee.io/v1/commissions/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "<string>",
  "tier_uuids": [
    "<string>"
  ],
  "category_uuids": [
    "<string>"
  ],
  "partnership_uuids": [
    "<string>"
  ]
}
'

{
  "uuid": "<string>",
  "label": "<string>",
  "payment_target": "<string>",
  "auto_assign_recipient": "<string>",
  "calculation": {
    "entries": [
      {
        "payment_stage_id": 123,
        "calculation": {
          "value": "<string>",
          "scalingConfig": {
            "customFieldId": 123,
            "tiers": [
              {
                "optionId": 123,
                "value": 123
              }
            ]
          },
          "number_of_occurrences": 123,
          "periodRates": {
            "enabled": true,
            "periods": [
              {
                "periodNumber": 123,
                "startOccurrence": 123,
                "endOccurrence": 123,
                "value": 123,
                "scalingConfig": {
                  "customFieldId": 123,
                  "tiers": [
                    {
                      "optionId": 123,
                      "value": 123
                    }
                  ]
                }
              }
            ]
          },
          "split": {
            "oneOff": {
              "value": "<string>",
              "scalingConfig": {
                "customFieldId": 123,
                "tiers": [
                  {
                    "optionId": 123,
                    "value": 123
                  }
                ]
              },
              "number_of_occurrences": 123,
              "periodRates": {
                "enabled": true,
                "periods": [
                  {
                    "periodNumber": 123,
                    "startOccurrence": 123,
                    "endOccurrence": 123,
                    "value": 123,
                    "scalingConfig": {
                      "customFieldId": 123,
                      "tiers": [
                        {
                          "optionId": 123,
                          "value": 123
                        }
                      ]
                    }
                  }
                ]
              }
            },
            "recurring": {
              "value": "<string>",
              "scalingConfig": {
                "customFieldId": 123,
                "tiers": [
                  {
                    "optionId": 123,
                    "value": 123
                  }
                ]
              },
              "number_of_occurrences": 123,
              "periodRates": {
                "enabled": true,
                "periods": [
                  {
                    "periodNumber": 123,
                    "startOccurrence": 123,
                    "endOccurrence": 123,
                    "value": 123,
                    "scalingConfig": {
                      "customFieldId": 123,
                      "tiers": [
                        {
                          "optionId": 123,
                          "value": 123
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        }
      }
    ]
  },
  "tiers": [
    {
      "uuid": "<string>",
      "label": "<string>"
    }
  ],
  "categories": [
    {
      "uuid": "<string>",
      "label": "<string>"
    }
  ],
  "partnerships": [
    {
      "uuid": "<string>",
      "name": "<string>"
    }
  ],
  "created_at": "<string>",
  "updated_at": "<string>"
}

Authorizations

Authorization

string

header

required

API key authentication. Use "Bearer <api_key>" or "Api-Key <api_key>".

Body

application/json

label

string

required

Commission rule name

partner_type

enum<string>

required

Which partner type this rule applies to

Available options:

referral,

reseller,

distributor

payment_target

enum<string> | null

partnership (partner org receives payment) or individual (specific user/contact)

Available options:

partnership,

individual

auto_assign_recipient

enum<string> | null

Available options:

lead_creator,

deal_owner,

manual

calculation

object

Commission calculation with one or more payment entries triggered by deal stage changes.

Show child attributes

tier_uuids

string[]

Restrict to partners in these tiers. Replaces current.

category_uuids

string[]

Restrict to partners in these categories. Replaces current.

partnership_uuids

string[]

Restrict to specific partnerships. Replaces current.

Response

201 - application/json

Default Response

uuid

string

required

label

string

required

partner_type

enum<string>

required

Available options:

referral,

reseller,

distributor

payment_target

string | null

required

auto_assign_recipient

string | null

required

calculation

object

required

Commission calculation with one or more payment entries triggered by deal stage changes.

Show child attributes

tiers

object[]

required

Show child attributes