Commissions API

REST endpoints for commissions in ServFlo: 8 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

Operation	Endpoint	Risk
List commission rules	`GET /organizations/{organizationId}/commission-rules`	`read`
Create a commission rule	`POST /organizations/{organizationId}/commission-rules`	`write`
Update a commission rule	`PATCH /organizations/{organizationId}/commission-rules/{commissionRuleId}`	`write`
Delete a commission rule	`DELETE /organizations/{organizationId}/commission-rules/{commissionRuleId}`	`sensitive`
The commission report for a period	`GET /organizations/{organizationId}/commissions`	`read`
Calculate commissions for a pay period	`POST /organizations/{organizationId}/commissions/calculate`	`write`
Approve commissions or mark them paid	`POST /organizations/{organizationId}/commissions/status`	`sensitive`
Export commissions as CSV	`GET /organizations/{organizationId}/commissions/export`	`read`

List commission rules

GET /organizations/{organizationId}/commission-rules

The organization's commission rules. Read-only.


Permission	`commissions.manage` (Owner, Admin)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`commissionRules_list` (toolset `team`)

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/commission-rules" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

An array of objects:

Field	Type	Description
`id`	string
`organizationId`	string
`name`	string
`type`	enum	JOB_REVENUE_PERCENT (percent of a completed job's revenue), SOLD_QUOTE_PERCENT (percent of quotes the technician sold, on approval), FLAT_PER_JOB, FLAT_PER_VISIT (completed), MEMBERSHIP_SALE_PERCENT (percent of a sold membership's term value). One of `JOB_REVENUE_PERCENT`, `SOLD_QUOTE_PERCENT`, `FLAT_PER_JOB`, `FLAT_PER_VISIT`, `MEMBERSHIP_SALE_PERCENT`.
`ratePercent`	number
`flatCents`	integer	Integer cents.
`split`	enum	Job and visit rules: LEAD (all to the lead technician) or CREW (split evenly). One of `LEAD`, `CREW`.
`technicianIds`	array of string
`active`	boolean
`createdAt`	string (date-time)
`updatedAt`	string (date-time)

Create a commission rule

POST /organizations/{organizationId}/commission-rules

Adds a rule (percent of job revenue, of sold quotes or of membership sales; flat per job or visit) for every technician or the ones named. It counts from the next calculation. Returns it.


Permission	`commissions.manage` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`commissionRules_create` (toolset `team`)

Request body

Field	Type	Required	Description
`name`	string	Yes	Up to 200 characters.
`type`	enum	Yes	JOB_REVENUE_PERCENT (percent of a completed job's revenue), SOLD_QUOTE_PERCENT (percent of quotes the technician sold, on approval), FLAT_PER_JOB, FLAT_PER_VISIT (completed), MEMBERSHIP_SALE_PERCENT (percent of a sold membership's term value). One of `JOB_REVENUE_PERCENT`, `SOLD_QUOTE_PERCENT`, `FLAT_PER_JOB`, `FLAT_PER_VISIT`, `MEMBERSHIP_SALE_PERCENT`.
`ratePercent`	number	No	For the percent types. 0–100.
`flatCents`	integer	No	For the flat types. 0–10000000.
`split`	enum	No	Job and visit rules: LEAD (all to the lead technician) or CREW (split evenly). One of `LEAD`, `CREW`.
`technicianIds`	array of string	No	Only these technicians earn from the rule; empty means everyone. Up to 500 items.
`active`	boolean	No

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/commission-rules" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dana Whitfield","type":"JOB_REVENUE_PERCENT"}'

Response

201: the answer's fields

Field	Type	Description
`id`	string
`organizationId`	string
`name`	string
`type`	enum	JOB_REVENUE_PERCENT (percent of a completed job's revenue), SOLD_QUOTE_PERCENT (percent of quotes the technician sold, on approval), FLAT_PER_JOB, FLAT_PER_VISIT (completed), MEMBERSHIP_SALE_PERCENT (percent of a sold membership's term value). One of `JOB_REVENUE_PERCENT`, `SOLD_QUOTE_PERCENT`, `FLAT_PER_JOB`, `FLAT_PER_VISIT`, `MEMBERSHIP_SALE_PERCENT`.
`ratePercent`	number
`flatCents`	integer	Integer cents.
`split`	enum	Job and visit rules: LEAD (all to the lead technician) or CREW (split evenly). One of `LEAD`, `CREW`.
`technicianIds`	array of string
`active`	boolean
`createdAt`	string (date-time)
`updatedAt`	string (date-time)

Update a commission rule

PATCH /organizations/{organizationId}/commission-rules/{commissionRuleId}

Changes the fields sent. Approved and paid commissions keep their amounts; pending ones follow at the next calculation. Returns it.


Permission	`commissions.manage` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`commissionRules_update` (toolset `team`)

Parameters

Name	In	Type	Required	Description
`commissionRuleId`	path	string	Yes

Request body

Field	Type	Required	Description
`name`	string	No	Up to 200 characters.
`type`	enum	No	JOB_REVENUE_PERCENT (percent of a completed job's revenue), SOLD_QUOTE_PERCENT (percent of quotes the technician sold, on approval), FLAT_PER_JOB, FLAT_PER_VISIT (completed), MEMBERSHIP_SALE_PERCENT (percent of a sold membership's term value). One of `JOB_REVENUE_PERCENT`, `SOLD_QUOTE_PERCENT`, `FLAT_PER_JOB`, `FLAT_PER_VISIT`, `MEMBERSHIP_SALE_PERCENT`.
`ratePercent`	number	No	For the percent types. 0–100.
`flatCents`	integer	No	For the flat types. 0–10000000.
`split`	enum	No	Job and visit rules: LEAD (all to the lead technician) or CREW (split evenly). One of `LEAD`, `CREW`.
`technicianIds`	array of string	No	Only these technicians earn from the rule; empty means everyone. Up to 500 items.
`active`	boolean	No

Example

curl -X PATCH "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/commission-rules/{commissionRuleId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dana Whitfield","type":"JOB_REVENUE_PERCENT","ratePercent":1}'

Response

200: the answer's fields

Field	Type	Description
`id`	string
`organizationId`	string
`name`	string
`type`	enum	JOB_REVENUE_PERCENT (percent of a completed job's revenue), SOLD_QUOTE_PERCENT (percent of quotes the technician sold, on approval), FLAT_PER_JOB, FLAT_PER_VISIT (completed), MEMBERSHIP_SALE_PERCENT (percent of a sold membership's term value). One of `JOB_REVENUE_PERCENT`, `SOLD_QUOTE_PERCENT`, `FLAT_PER_JOB`, `FLAT_PER_VISIT`, `MEMBERSHIP_SALE_PERCENT`.
`ratePercent`	number
`flatCents`	integer	Integer cents.
`split`	enum	Job and visit rules: LEAD (all to the lead technician) or CREW (split evenly). One of `LEAD`, `CREW`.
`technicianIds`	array of string
`active`	boolean
`createdAt`	string (date-time)
`updatedAt`	string (date-time)

Delete a commission rule

DELETE /organizations/{organizationId}/commission-rules/{commissionRuleId}

Destructive: deletes the rule and its pending commissions; refused (400) when it has approved or paid ones (turn it off instead).


Permission	`commissions.manage` (Owner, Admin)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`commissionRules_delete` (toolset `team`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Parameters

Name	In	Type	Required	Description
`commissionRuleId`	path	string	Yes

Example

curl -X DELETE "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/commission-rules/{commissionRuleId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`ok`	true

The commission report for a period

GET /organizations/{organizationId}/commissions

Commission lines whose source falls in the period (start/end), by technician or status, with totals per technician (pending, approved, paid). A technician sees only their own lines. Calculate the period first with POST /commissions/calculate. Read-only.

Permission: commissions.read (Owner, Admin, Technician (own commissions)); risk read (OAuth scope servflo.read).


Permission	`commissions.read`
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`commissions_list` (toolset `team`)

Parameters

Name	In	Type	Required	Description
`start`	query	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.
`end`	query	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.
`technicianId`	query	string	No
`status`	query	enum	No	PENDING (recomputed on each calculation), APPROVED, PAID (never recomputed). One of `PENDING`, `APPROVED`, `PAID`.
`limit`	query	integer	No	Page size, 1–200. Default `50`.
`offset`	query	integer	No	Rows to skip; the answer's `total` counts every match. Default `0`.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/commissions" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`items`	array of object
`items[].id`	string
`items[].ruleId`	string
`items[].technicianId`	string
`items[].sourceType`	string	JOB, VISIT, QUOTE or MEMBERSHIP.
`items[].sourceId`	string
`items[].sourceIdentifier`	string
`items[].sourceDate`	string
`items[].periodStart`	string
`items[].periodEnd`	string
`items[].basisCents`	integer	Integer cents.
`items[].ratePercent`	number or null
`items[].amountCents`	integer	Integer cents.
`items[].status`	enum	PENDING (recomputed on each calculation), APPROVED, PAID (never recomputed). One of `PENDING`, `APPROVED`, `PAID`.
`items[].approvedAt`	string (date-time) or null
`items[].paidAt`	string (date-time) or null
`items[].technician`	object
`items[].technician.id`	string
`items[].technician.name`	string
`items[].technician.color`	string
`items[].rule`	object
`items[].rule.id`	string
`items[].rule.name`	string
`items[].rule.type`	enum	JOB_REVENUE_PERCENT (percent of a completed job's revenue), SOLD_QUOTE_PERCENT (percent of quotes the technician sold, on approval), FLAT_PER_JOB, FLAT_PER_VISIT (completed), MEMBERSHIP_SALE_PERCENT (percent of a sold membership's term value). One of `JOB_REVENUE_PERCENT`, `SOLD_QUOTE_PERCENT`, `FLAT_PER_JOB`, `FLAT_PER_VISIT`, `MEMBERSHIP_SALE_PERCENT`.
`items[].rule.split`	enum	Job and visit rules: LEAD (all to the lead technician) or CREW (split evenly). One of `LEAD`, `CREW`.
`total`	integer
`totals`	array of object
`totals[].technicianId`	string
`totals[].name`	string
`totals[].color`	string
`totals[].pendingCents`	integer	Integer cents.
`totals[].approvedCents`	integer	Integer cents.
`totals[].paidCents`	integer	Integer cents.
`totals[].totalCents`	integer	Integer cents.
`totalCents`	integer	Integer cents.

Calculate commissions for a pay period

POST /organizations/{organizationId}/commissions/calculate

Computes every commission the active rules earn from jobs and visits completed, quotes approved and memberships sold in the period, and writes them as PENDING lines. Idempotent: a source is paid once (unique per rule, technician and source); pending lines are recomputed, approved and paid ones are never changed. Returns the counts.


Permission	`commissions.manage` (Owner, Admin)
Risk	`write`, OAuth scope `servflo.write`. Write: creates or changes records inside the business; nothing leaves it.
MCP tool	`commissions_calculate` (toolset `team`)

Request body

Field	Type	Required	Description
`start`	string	Yes	First day of the pay period.
`end`	string	Yes	Last day of the pay period (inclusive).

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/commissions/calculate" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start":"string","end":"string"}'

Response

200: the answer's fields

Field	Type	Description
`created`	integer
`updated`	integer
`settled`	integer	Lines already approved or paid, left as they were.
`removed`	integer	Pending lines no longer earned.
`lines`	integer
`totalCents`	integer	Integer cents.
`period`	object
`period.start`	string
`period.end`	string

Approve commissions or mark them paid

POST /organizations/{organizationId}/commissions/status

MONEY (pay): moves lines PENDING → APPROVED → PAID (or APPROVED back to PENDING). Paid lines never change. Approved and paid lines are kept through recalculations. Returns how many changed.


Permission	`commissions.manage` (Owner, Admin)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`commissions_setStatus` (toolset `team`)
Approval	Over MCP, this tool always waits for your approval in ServFlo. See Approvals.

Request body

Field	Type	Required	Description
`lineIds`	array of string	Yes	Up to 1000 items.
`status`	enum	Yes	PENDING (recomputed on each calculation), APPROVED, PAID (never recomputed). One of `PENDING`, `APPROVED`, `PAID`.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/commissions/status" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lineIds":["line_id"],"status":"PENDING"}'

Response

200: the answer's fields

Field	Type	Description
`updated`	integer

Export commissions as CSV

GET /organizations/{organizationId}/commissions/export

The period's lines as CSV (technician, rule, source, date, basis, rate, amount, status) for payroll. A technician exports only their own. Read-only.

Permission: commissions.read (Owner, Admin, Technician (own commissions)); risk read (OAuth scope servflo.read).


Permission	`commissions.read`
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`commissions_export` (toolset `team`)

Parameters

Name	In	Type	Required	Description
`start`	query	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.
`end`	query	string	No	A calendar date in the business's own calendar, YYYY-MM-DD.
`technicianId`	query	string	No
`status`	query	enum	No	PENDING (recomputed on each calculation), APPROVED, PAID (never recomputed). One of `PENDING`, `APPROVED`, `PAID`.

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/commissions/export" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`fileName`	string
`csv`	string
`count`	integer

On this page