Kpi settings

Employee KPI configuration

INFO

Every response arrives in the shared envelope — code, message, messages, status_code, time — with the payload in data. The tables below describe what is inside data.

POST /kpi-settings/create

Create a new KPI settings record for a given period and set of employees.

Request body

Field	Type	Required	Description
`organization_id`	`string`	Yes	Organization ObjectId this KPI setting belongs to
`name`	`string`	No	Optional display name for the KPI setting
`currency_id`	`string`	Yes	Currency ObjectId used for monetary KPI metrics
`user_ids`	`string[]`	Yes	ObjectIds of the employees this KPI setting applies to
`period`	`string`	Yes	KPI evaluation period. One of: `week`, `month`, `quarter`, `year`
`calculation_method`	`string`	Yes	How the bonus is calculated across tiers: progressive (each tier adds to the previous) or threshold (only the matched tier applies). One of: `progressive`, `threshold`
`date_from`	`string (date-time)`	Yes	Start date of the KPI period
`date_to`	`string (date-time)`	Yes	End date of the KPI period
`year`	`number`	Yes	Calendar year of the KPI period
`quarter`	`string`	No	Quarter label (e.g. Q1) when period is quarter
`month`	`string`	No	Month label when period is month
`week`	`string`	No	Week label when period is week
`filter_enabled`	`boolean`	No	Whether product/customer filters are active for this KPI setting. Default: `false`
`filter`	`object`	No	Optional product and customer scope filters
`filter.is_all_categories`	`boolean`	No
`filter.customer_category_ids`	`string[]`	No	Customer category ObjectIds to include
`filter.customer_nested_category_ids`	`string[]`	No
`filter.customer_ids`	`string[]`	No	Specific customer ObjectIds to include
`filter.product_category_ids`	`string[]`	No
`filter.product_nested_category_ids`	`string[]`	No
`filter.product_ids`	`string[]`	No	Specific product ObjectIds to include
`conditions`	`object[]`	Yes	One or more KPI plan conditions defining the performance metric and tier thresholds
`conditions[].logical_operator`	`boolean`	Yes	true = AND with the next condition, false = OR
`conditions[].source_metric_code`	`string`	Yes	The performance metric used to evaluate this condition. One of: `net_sales`, `sales_count`, `avg_net_sales`, `profit`, `paid`, `paid_percent`, `items_sold`
`conditions[].tiers`	`object[]`	Yes	Threshold tiers for this condition
`conditions[].tiers[].min_value`	`number`	Yes	Minimum metric value for this tier to activate
`conditions[].tiers[].max_value`	`number`	No	Maximum metric value for this tier (omit for the top tier)
`bonus_metric_code`	`string`	Yes	How the bonus amount is computed from the employee's results. One of: `percent_of_net_sales`, `percent_of_payment`, `percent_of_profit`, `per_sale`, `fixed_amount`, `per_item_sold`
`bonuses`	`number[]`	Yes	Bonus amounts or percentages, one entry per tier in the conditions

json

{
  "organization_id": "string",
  "name": "string",
  "currency_id": "string",
  "user_ids": [
    "string"
  ],
  "period": "week",
  "calculation_method": "progressive",
  "date_from": "2025-05-01T12:00:00Z",
  "date_to": "2025-05-01T12:00:00Z",
  "year": 0,
  "quarter": "string",
  "month": "string",
  "week": "string",
  "filter_enabled": false,
  "filter": {
    "is_all_categories": false,
    "customer_category_ids": [
      "string"
    ],
    "customer_nested_category_ids": [
      "string"
    ],
    "customer_ids": [
      "string"
    ],
    "product_category_ids": [
      "string"
    ],
    "product_nested_category_ids": [
      "string"
    ],
    "product_ids": [
      "string"
    ]
  },
  "conditions": [
    {
      "logical_operator": false,
      "source_metric_code": "net_sales",
      "tiers": []
    }
  ],
  "bonus_metric_code": "percent_of_net_sales",
  "bonuses": [
    0
  ]
}

Response

Field	Type	Description
`_id`	`string`	KPI settings ObjectId
`organization_id`	`string`
`name`	`string`
`currency_id`	`string`
`user_ids`	`string[]`
`period`	`string`	One of: `week`, `month`, `quarter`, `year`
`calculation_method`	`string`	One of: `progressive`, `threshold`
`state`	`string`	One of: `draft`, `active`, `locked`, `approved`, `canceled`
`date_from`	`string (date-time)`
`date_to`	`string (date-time)`
`year`	`number`
`quarter`	`string`
`month`	`string`
`week`	`string`
`filter_enabled`	`boolean`
`filter`	`object`
`filter.is_all_categories`	`boolean`
`filter.customer_category_ids`	`string[]`
`filter.customer_nested_category_ids`	`string[]`
`filter.customer_ids`	`string[]`
`filter.product_category_ids`	`string[]`
`filter.product_nested_category_ids`	`string[]`
`filter.product_ids`	`string[]`
`conditions`	`object[]`
`conditions[].logical_operator`	`boolean`
`conditions[].source_metric_code`	`string`	One of: `net_sales`, `sales_count`, `avg_net_sales`, `profit`, `paid`, `paid_percent`, `items_sold`
`conditions[].tiers`	`object[]`
`conditions[].tiers[].min_value`	`number`
`conditions[].tiers[].max_value`	`number`
`bonus_metric_code`	`string`	One of: `percent_of_net_sales`, `percent_of_payment`, `percent_of_profit`, `per_sale`, `fixed_amount`, `per_item_sold`
`bonuses`	`number[]`
`created_at`	`string (date-time)`
`updated_at`	`string (date-time)`
`is_deleted`	`boolean`

json

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "_id": "string",
    "organization_id": "string",
    "name": "string",
    "currency_id": "string",
    "user_ids": [
      "string"
    ],
    "period": "week",
    "calculation_method": "progressive",
    "state": "draft",
    "date_from": "2025-05-01T12:00:00Z",
    "date_to": "2025-05-01T12:00:00Z",
    "year": 0,
    "quarter": "string",
    "month": "string",
    "week": "string",
    "filter_enabled": false,
    "filter": {
      "is_all_categories": false,
      "customer_category_ids": [
        "string"
      ],
      "customer_nested_category_ids": [
        "string"
      ],
      "customer_ids": [
        "string"
      ],
      "product_category_ids": [
        "string"
      ],
      "product_nested_category_ids": [
        "string"
      ],
      "product_ids": [
        "string"
      ]
    },
    "conditions": [
      {
        "logical_operator": false,
        "source_metric_code": "net_sales",
        "tiers": []
      }
    ],
    "bonus_metric_code": "percent_of_net_sales",
    "bonuses": [
      0
    ],
    "created_at": "2025-05-01T12:00:00Z",
    "updated_at": "2025-05-01T12:00:00Z",
    "is_deleted": false
  },
  "time": "2025-05-01T12:00:00Z"
}

GET /kpi-settings/get-by-id/{id}

Fetch a single KPI settings record by ObjectId.

Path parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	KPI settings ObjectId

Request body

No request body.

Response

Same response shape as POST /kpi-settings/create.

POST /kpi-settings/get-paging

Paginated list of KPI settings records, optionally filtered by organization or period.

Request body

Field	Type	Required	Description
`page`	`number`	Yes	Default: `1`
`limit`	`number`	Yes	Default: `20`
`organization_id`	`string`	No	Filter by organization ObjectId
`period`	`string`	No	Filter by KPI period. One of: `week`, `month`, `quarter`, `year`
`state`	`string`	No	Filter by KPI settings state. One of: `draft`, `active`, `locked`, `approved`, `canceled`

json

{
  "page": 1,
  "limit": 20,
  "organization_id": "string",
  "period": "week",
  "state": "draft"
}

Response

Field	Type	Description
`total`	`number`
`list`	`object[]`
`list[]._id`	`string`	KPI settings ObjectId
`list[].organization_id`	`string`
`list[].name`	`string`
`list[].currency_id`	`string`
`list[].user_ids`	`string[]`
`list[].period`	`string`	One of: `week`, `month`, `quarter`, `year`
`list[].calculation_method`	`string`	One of: `progressive`, `threshold`
`list[].state`	`string`	One of: `draft`, `active`, `locked`, `approved`, `canceled`
`list[].date_from`	`string (date-time)`
`list[].date_to`	`string (date-time)`
`list[].year`	`number`
`list[].quarter`	`string`
`list[].month`	`string`
`list[].week`	`string`
`list[].filter_enabled`	`boolean`
`list[].filter`	`object`
`list[].filter.is_all_categories`	`boolean`
`list[].filter.customer_category_ids`	`string[]`
`list[].filter.customer_nested_category_ids`	`string[]`
`list[].filter.customer_ids`	`string[]`
`list[].filter.product_category_ids`	`string[]`
`list[].filter.product_nested_category_ids`	`string[]`
`list[].filter.product_ids`	`string[]`
`list[].conditions`	`object[]`
`list[].conditions[].logical_operator`	`boolean`
`list[].conditions[].source_metric_code`	`string`	One of: `net_sales`, `sales_count`, `avg_net_sales`, `profit`, `paid`, `paid_percent`, `items_sold`
`list[].conditions[].tiers`	`object[]`
`list[].bonus_metric_code`	`string`	One of: `percent_of_net_sales`, `percent_of_payment`, `percent_of_profit`, `per_sale`, `fixed_amount`, `per_item_sold`
`list[].bonuses`	`number[]`
`list[].created_at`	`string (date-time)`
`list[].updated_at`	`string (date-time)`
`list[].is_deleted`	`boolean`

json

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "total": 0,
    "list": [
      {
        "_id": "string",
        "organization_id": "string",
        "name": "string",
        "currency_id": "string",
        "user_ids": [],
        "period": "week",
        "calculation_method": "progressive",
        "state": "draft",
        "date_from": "2025-05-01T12:00:00Z",
        "date_to": "2025-05-01T12:00:00Z",
        "year": 0,
        "quarter": "string",
        "month": "string",
        "week": "string",
        "filter_enabled": false,
        "filter": {
          "is_all_categories": null,
          "customer_category_ids": null,
          "customer_nested_category_ids": null,
          "customer_ids": null,
          "product_category_ids": null,
          "product_nested_category_ids": null,
          "product_ids": null
        },
        "conditions": [],
        "bonus_metric_code": "percent_of_net_sales",
        "bonuses": [],
        "created_at": "2025-05-01T12:00:00Z",
        "updated_at": "2025-05-01T12:00:00Z",
        "is_deleted": false
      }
    ]
  },
  "time": "2025-05-01T12:00:00Z"
}

PUT /kpi-settings/update/{id}

Update an existing KPI settings record.

Path parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	KPI settings ObjectId

Request body

Field	Type	Required	Description
`organization_id`	`string`	Yes	Organization ObjectId this KPI setting belongs to
`name`	`string`	No	Optional display name for the KPI setting
`currency_id`	`string`	Yes	Currency ObjectId used for monetary KPI metrics
`user_ids`	`string[]`	Yes	ObjectIds of the employees this KPI setting applies to
`period`	`string`	Yes	KPI evaluation period. One of: `week`, `month`, `quarter`, `year`
`calculation_method`	`string`	Yes	How the bonus is calculated across tiers: progressive (each tier adds to the previous) or threshold (only the matched tier applies). One of: `progressive`, `threshold`
`date_from`	`string (date-time)`	Yes	Start date of the KPI period
`date_to`	`string (date-time)`	Yes	End date of the KPI period
`year`	`number`	Yes	Calendar year of the KPI period
`quarter`	`string`	No	Quarter label (e.g. Q1) when period is quarter
`month`	`string`	No	Month label when period is month
`week`	`string`	No	Week label when period is week
`filter_enabled`	`boolean`	No	Whether product/customer filters are active for this KPI setting. Default: `false`
`filter`	`object`	No	Optional product and customer scope filters
`filter.is_all_categories`	`boolean`	No
`filter.customer_category_ids`	`string[]`	No	Customer category ObjectIds to include
`filter.customer_nested_category_ids`	`string[]`	No
`filter.customer_ids`	`string[]`	No	Specific customer ObjectIds to include
`filter.product_category_ids`	`string[]`	No
`filter.product_nested_category_ids`	`string[]`	No
`filter.product_ids`	`string[]`	No	Specific product ObjectIds to include
`conditions`	`object[]`	Yes	One or more KPI plan conditions defining the performance metric and tier thresholds
`conditions[].logical_operator`	`boolean`	Yes	true = AND with the next condition, false = OR
`conditions[].source_metric_code`	`string`	Yes	The performance metric used to evaluate this condition. One of: `net_sales`, `sales_count`, `avg_net_sales`, `profit`, `paid`, `paid_percent`, `items_sold`
`conditions[].tiers`	`object[]`	Yes	Threshold tiers for this condition
`conditions[].tiers[].min_value`	`number`	Yes	Minimum metric value for this tier to activate
`conditions[].tiers[].max_value`	`number`	No	Maximum metric value for this tier (omit for the top tier)
`bonus_metric_code`	`string`	Yes	How the bonus amount is computed from the employee's results. One of: `percent_of_net_sales`, `percent_of_payment`, `percent_of_profit`, `per_sale`, `fixed_amount`, `per_item_sold`
`bonuses`	`number[]`	Yes	Bonus amounts or percentages, one entry per tier in the conditions

json

{
  "organization_id": "string",
  "name": "string",
  "currency_id": "string",
  "user_ids": [
    "string"
  ],
  "period": "week",
  "calculation_method": "progressive",
  "date_from": "2025-05-01T12:00:00Z",
  "date_to": "2025-05-01T12:00:00Z",
  "year": 0,
  "quarter": "string",
  "month": "string",
  "week": "string",
  "filter_enabled": false,
  "filter": {
    "is_all_categories": false,
    "customer_category_ids": [
      "string"
    ],
    "customer_nested_category_ids": [
      "string"
    ],
    "customer_ids": [
      "string"
    ],
    "product_category_ids": [
      "string"
    ],
    "product_nested_category_ids": [
      "string"
    ],
    "product_ids": [
      "string"
    ]
  },
  "conditions": [
    {
      "logical_operator": false,
      "source_metric_code": "net_sales",
      "tiers": []
    }
  ],
  "bonus_metric_code": "percent_of_net_sales",
  "bonuses": [
    0
  ]
}

Response

Same response shape as POST /kpi-settings/create.

DELETE /kpi-settings/delete/{id}

Soft-delete a KPI settings record by ObjectId.

Path parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	KPI settings ObjectId

Request body

No request body.

Response

json

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": "ok",
  "time": "2025-05-01T12:00:00Z"
}

PUT /kpi-settings/set-status/{id}

Change the status (state) of a KPI settings record. Allowed transitions: locked, approved, canceled.

Path parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	KPI settings ObjectId

Request body

Field	Type	Required	Description
`status`	`string`	Yes	New status for the KPI settings record. One of: `locked`, `approved`, `canceled`

json

{
  "status": "locked"
}

Response

Same response shape as POST /kpi-settings/create.

This page is generated from the OpenAPI spec.

Kpi settings ​

POST /kpi-settings/create ​

GET /kpi-settings/get-by-id/{id} ​

POST /kpi-settings/get-paging ​

PUT /kpi-settings/update/{id} ​

DELETE /kpi-settings/delete/{id} ​

PUT /kpi-settings/set-status/{id} ​

Kpi settings

POST /kpi-settings/create

GET /kpi-settings/get-by-id/{id}

POST /kpi-settings/get-paging

PUT /kpi-settings/update/{id}

DELETE /kpi-settings/delete/{id}

PUT /kpi-settings/set-status/{id}