Commission payouts, statements
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Use this when the user wants to calculate sales commission for one rep: a flat rate, a tiered commission ("5% up to 50k then 8% above"), quota attainment with accelerators or decelerators, a cap, a draw against commission, split deals ("split commission 60/40"), SPIFFs, clawbacks for refunded or cancelled deals, gross-margin commission, or OTE/target variable pay. Give either a sales_total or the deals. Returns the commission per deal with the tier applied, the tier breakdown, marginal and retroactive results when the plan does not say which, the draw recovery, the amount payable now, and a PDF commission statement plus an Excel file. Does not compute taxes or take-home pay. Do not use for a whole team or an uploaded deals file (use generate_commission_statements) or for commission-free trading.
The commission plan terms: rate or tiers, quota, cap, draw, clawback rules, e.g. {"tiers":[{"up_to":50000,"rate":5},{"up_to":null,"rate":8}]}.
The rep's deals for the period, e.g. [{"deal":"Acme","amount":24000,"close_date":"2026-09-14"},{"deal":"Globex","amount":18000,"split_percent":60}].
ISO currency code, default USD, e.g. CAD or EUR.
Rep name for the statement, e.g. "Maria Lopez".
Last day of the period, e.g. 2026-09-30.
Total credited sales for the period when there are no individual deals, e.g. 72000.
Company name printed on the statement, e.g. "Acme Corp".
Label printed on statements, e.g. "September 2026" or "Q3 2026".
First day of the commission period, e.g. 2026-09-01. Deals closed outside the period are not counted.
Unrecovered draw or clawback balance owed from earlier periods, e.g. 1500.
Use this when the user wants to calculate sales commission for one rep: a flat rate, a tiered commission ("5% up to 50k then 8% above"), quota attainment with accelerators or decelerators, a cap, a draw against commission, split deals ("split commission 60/40"), SPIFFs, clawbacks for refunded or cancelled deals, gross-margin commission, or OTE/target variable pay. Give either a sales_total or the deals. Returns the commission per deal with the tier applied, the tier breakdown, marginal and retroactive results when the plan does not say which, the draw recovery, the amount payable now, and a PDF commission statement plus an Excel file. Does not compute taxes or take-home pay. Do not use for a whole team or an uploaded deals file (use generate_commission_statements) or for commission-free trading.
| Argument | Type | Description |
|---|---|---|
| plan* | object | The commission plan terms: rate or tiers, quota, cap, draw, clawback rules, e.g. {"tiers":[{"up_to":50000,"rate":5},{"up_to":null,"rate":8}]}. |
| deals | array | The rep's deals for the period, e.g. [{"deal":"Acme","amount":24000,"close_date":"2026-09-14"},{"deal":"Globex","amount":18000,"split_percent":60}]. |
| currency | string | ISO currency code, default USD, e.g. CAD or EUR. |
| rep_name | string | Rep name for the statement, e.g. "Maria Lopez". |
| period_end | string | Last day of the period, e.g. 2026-09-30. |
| sales_total | number | Total credited sales for the period when there are no individual deals, e.g. 72000. |
| company_name | string | Company name printed on the statement, e.g. "Acme Corp". |
| period_label | string | Label printed on statements, e.g. "September 2026" or "Q3 2026". |
| period_start | string | First day of the commission period, e.g. 2026-09-01. Deals closed outside the period are not counted. |
| prior_balance | number | Unrecovered draw or clawback balance owed from earlier periods, e.g. 1500. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"plan"
],
"properties": {
"plan": {
"type": "object",
"properties": {
"ote": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "On-target earnings for the period, e.g. 30000; use with base_salary to derive target variable pay = OTE - base salary."
},
"name": {
"type": "string",
"maxLength": 60,
"description": "Plan label, e.g. \"AE plan FY26\" or \"Plan A\"."
},
"rate": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Flat commission rate in percent, e.g. 10 for 10%. With tiers that use multipliers this is the base commission rate."
},
"quota": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Quota for the period in currency, e.g. 150000. Used for attainment and quota-percent tiers."
},
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Commission rate for this tier in percent, e.g. 8 for 8%."
},
"up_to": {
"anyOf": [
{
"type": "number",
"maximum": 100000000000,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Upper limit of this tier, inclusive, in currency (e.g. 50000) or in percent of quota when tier_unit is quota_percent (e.g. 100). Leave null on the last, open-ended tier."
},
"multiplier": {
"anyOf": [
{
"type": "number",
"maximum": 20,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Instead of a rate: a multiple of the base commission rate, e.g. 1.5 for an accelerator above quota or 0.5 for a decelerator below 50% of quota."
}
}
},
"maxItems": 12,
"description": "Tiered rates in ascending order. \"5% up to 50k then 8% above\" = [{\"up_to\":50000,\"rate\":5},{\"up_to\":null,\"rate\":8}]. Accelerator over quota with tier_unit quota_percent: [{\"up_to\":100,\"rate\":10},{\"up_to\":null,\"rate\":15}]."
},
"bonuses": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"amount"
],
"properties": {
"label": {
"type": "string",
"maxLength": 80,
"description": "Bonus or SPIFF name, e.g. \"Q3 new-logo SPIFF\"."
},
"amount": {
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000,
"description": "Amount, e.g. 500."
}
}
},
"maxItems": 20,
"description": "One-off bonuses or SPIFFs for the period, outside tiers and the cap, e.g. [{\"label\":\"President's club SPIFF\",\"amount\":1000}]."
},
"draw_type": {
"enum": [
"recoverable",
"non_recoverable"
],
"type": "string",
"description": "recoverable (default: a shortfall carries forward and is repaid from later commission) or non_recoverable (the shortfall is forgiven, not repaid)."
},
"tier_unit": {
"enum": [
"amount",
"quota_percent"
],
"type": "string",
"description": "Tier limits in currency (amount, default) or in percent of quota attainment (quota_percent, needs quota)."
},
"cap_amount": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Maximum commission on deals for the period, e.g. 25000. SPIFFs and bonuses are outside the cap."
},
"base_salary": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Base salary for the same period as ote, e.g. 15000."
},
"draw_amount": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Draw against commission paid for the period, e.g. 3000."
},
"tier_method": {
"enum": [
"marginal",
"retroactive"
],
"type": "string",
"description": "marginal (stepped: each slice of sales at its own tier rate) or retroactive (all sales at the rate of the highest tier reached). Leave out when the plan wording does not say; both results are then shown."
},
"commission_base": {
"enum": [
"revenue",
"gross_margin"
],
"type": "string",
"description": "What the rate applies to: revenue (deal amount, default) or gross_margin (each deal's margin or margin_percent)."
},
"target_variable": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Target variable (incentive) pay at 100% of quota for the period, e.g. 15000. With quota it sets the base commission rate = target_variable / quota."
},
"clawback_percent": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Share of the original commission clawed back, in percent, default 100."
},
"clawback_window_days": {
"type": "integer",
"maximum": 3650,
"minimum": 0,
"description": "Days after close in which a refund or cancellation claws back commission, e.g. 90. Leave out to claw back any cancellation."
},
"unknown_status_as_won": {
"type": "boolean",
"description": "Count deals whose status is not recognised (e.g. \"Signed - pending\") as closed-won. Default false: they are listed as not counted."
}
},
"description": "The commission plan terms: rate or tiers, quota, cap, draw, clawback rules, e.g. {\"tiers\":[{\"up_to\":50000,\"rate\":5},{\"up_to\":null,\"rate\":8}]}."
},
"deals": {
"type": "array",
"items": {
"type": "object",
"required": [
"amount"
],
"properties": {
"deal": {
"type": "string",
"maxLength": 120,
"description": "Deal, customer or invoice name, e.g. \"Acme renewal\"."
},
"spiff": {
"anyOf": [
{
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000
},
{
"type": "null"
}
],
"description": "SPIFF paid on this deal, e.g. 250 (outside tiers and cap; split with the deal)."
},
"amount": {
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000,
"description": "Deal amount (revenue) in currency, e.g. 24000. Negative = credit or adjustment."
},
"margin": {
"anyOf": [
{
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000
},
{
"type": "null"
}
],
"description": "Gross margin amount of the deal, e.g. 7200 (for gross_margin plans)."
},
"status": {
"anyOf": [
{
"type": "string",
"maxLength": 40
},
{
"type": "null"
}
],
"description": "Deal status, e.g. won (default), refunded, cancelled, churned, chargeback, lost, open. Cancelled deals are clawed back; lost and open deals are not counted."
},
"close_date": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
],
"description": "Close date, e.g. 2026-09-14 or 9/14/2026 (US order). Sets the order in which deals fill tiers."
},
"cancel_date": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
],
"description": "Refund or cancellation date for the clawback window, e.g. 2026-10-20."
},
"split_percent": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": 0
},
{
"type": "null"
}
],
"description": "This rep's share of the deal in percent, e.g. 60 for a 60/40 split. Default 100."
},
"margin_percent": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": -100
},
{
"type": "null"
}
],
"description": "Gross margin in percent of the amount, e.g. 30 (alternative to margin)."
},
"commission_paid": {
"anyOf": [
{
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000
},
{
"type": "null"
}
],
"description": "For a refunded deal from an earlier period: commission already paid on it, e.g. 1200. The clawback uses this amount."
}
}
},
"maxItems": 500,
"description": "The rep's deals for the period, e.g. [{\"deal\":\"Acme\",\"amount\":24000,\"close_date\":\"2026-09-14\"},{\"deal\":\"Globex\",\"amount\":18000,\"split_percent\":60}]."
},
"currency": {
"type": "string",
"maxLength": 3,
"description": "ISO currency code, default USD, e.g. CAD or EUR."
},
"rep_name": {
"type": "string",
"maxLength": 80,
"description": "Rep name for the statement, e.g. \"Maria Lopez\"."
},
"period_end": {
"type": "string",
"maxLength": 30,
"description": "Last day of the period, e.g. 2026-09-30."
},
"sales_total": {
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000,
"description": "Total credited sales for the period when there are no individual deals, e.g. 72000."
},
"company_name": {
"type": "string",
"maxLength": 80,
"description": "Company name printed on the statement, e.g. \"Acme Corp\"."
},
"period_label": {
"type": "string",
"maxLength": 60,
"description": "Label printed on statements, e.g. \"September 2026\" or \"Q3 2026\"."
},
"period_start": {
"type": "string",
"maxLength": 30,
"description": "First day of the commission period, e.g. 2026-09-01. Deals closed outside the period are not counted."
},
"prior_balance": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Unrecovered draw or clawback balance owed from earlier periods, e.g. 1500."
}
}
}Use this when the user wants to compare two commission plans or comp plans ("compare these two comp plans", "which plan pays more at 120% of quota"): computes the commission each plan pays at several sales levels, the difference, and where one plan overtakes the other, with tiers, accelerators, quota percentages and caps applied, computed in cents. Does not handle draws, deal lists or taxes, and does not judge which plan is fair. Do not use for a single plan's payout (use calculate_commission).
| Argument | Type | Description |
|---|---|---|
| plan_a* | object | First plan, e.g. {"name":"Flat 10%","rate":10}. |
| plan_b* | object | Second plan, e.g. {"name":"Accelerated","quota":100000,"tier_unit":"quota_percent","tiers":[{"up_to":100,"rate":8},{"up_to":null,"rate":14}]}. |
| currency | string | ISO currency code, default USD, e.g. CAD or EUR. |
| sales_levels | array | Sales totals to compare at, e.g. [50000, 100000, 150000]. Default: 50% to 200% of the quota. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"plan_a",
"plan_b"
],
"properties": {
"plan_a": {
"type": "object",
"properties": {
"ote": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "On-target earnings for the period, e.g. 30000; use with base_salary to derive target variable pay = OTE - base salary."
},
"name": {
"type": "string",
"maxLength": 60,
"description": "Plan label, e.g. \"AE plan FY26\" or \"Plan A\"."
},
"rate": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Flat commission rate in percent, e.g. 10 for 10%. With tiers that use multipliers this is the base commission rate."
},
"quota": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Quota for the period in currency, e.g. 150000. Used for attainment and quota-percent tiers."
},
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Commission rate for this tier in percent, e.g. 8 for 8%."
},
"up_to": {
"anyOf": [
{
"type": "number",
"maximum": 100000000000,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Upper limit of this tier, inclusive, in currency (e.g. 50000) or in percent of quota when tier_unit is quota_percent (e.g. 100). Leave null on the last, open-ended tier."
},
"multiplier": {
"anyOf": [
{
"type": "number",
"maximum": 20,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Instead of a rate: a multiple of the base commission rate, e.g. 1.5 for an accelerator above quota or 0.5 for a decelerator below 50% of quota."
}
}
},
"maxItems": 12,
"description": "Tiered rates in ascending order. \"5% up to 50k then 8% above\" = [{\"up_to\":50000,\"rate\":5},{\"up_to\":null,\"rate\":8}]. Accelerator over quota with tier_unit quota_percent: [{\"up_to\":100,\"rate\":10},{\"up_to\":null,\"rate\":15}]."
},
"bonuses": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"amount"
],
"properties": {
"label": {
"type": "string",
"maxLength": 80,
"description": "Bonus or SPIFF name, e.g. \"Q3 new-logo SPIFF\"."
},
"amount": {
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000,
"description": "Amount, e.g. 500."
}
}
},
"maxItems": 20,
"description": "One-off bonuses or SPIFFs for the period, outside tiers and the cap, e.g. [{\"label\":\"President's club SPIFF\",\"amount\":1000}]."
},
"draw_type": {
"enum": [
"recoverable",
"non_recoverable"
],
"type": "string",
"description": "recoverable (default: a shortfall carries forward and is repaid from later commission) or non_recoverable (the shortfall is forgiven, not repaid)."
},
"tier_unit": {
"enum": [
"amount",
"quota_percent"
],
"type": "string",
"description": "Tier limits in currency (amount, default) or in percent of quota attainment (quota_percent, needs quota)."
},
"cap_amount": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Maximum commission on deals for the period, e.g. 25000. SPIFFs and bonuses are outside the cap."
},
"base_salary": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Base salary for the same period as ote, e.g. 15000."
},
"draw_amount": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Draw against commission paid for the period, e.g. 3000."
},
"tier_method": {
"enum": [
"marginal",
"retroactive"
],
"type": "string",
"description": "marginal (stepped: each slice of sales at its own tier rate) or retroactive (all sales at the rate of the highest tier reached). Leave out when the plan wording does not say; both results are then shown."
},
"commission_base": {
"enum": [
"revenue",
"gross_margin"
],
"type": "string",
"description": "What the rate applies to: revenue (deal amount, default) or gross_margin (each deal's margin or margin_percent)."
},
"target_variable": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Target variable (incentive) pay at 100% of quota for the period, e.g. 15000. With quota it sets the base commission rate = target_variable / quota."
},
"clawback_percent": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Share of the original commission clawed back, in percent, default 100."
},
"clawback_window_days": {
"type": "integer",
"maximum": 3650,
"minimum": 0,
"description": "Days after close in which a refund or cancellation claws back commission, e.g. 90. Leave out to claw back any cancellation."
},
"unknown_status_as_won": {
"type": "boolean",
"description": "Count deals whose status is not recognised (e.g. \"Signed - pending\") as closed-won. Default false: they are listed as not counted."
}
},
"description": "First plan, e.g. {\"name\":\"Flat 10%\",\"rate\":10}."
},
"plan_b": {
"type": "object",
"properties": {
"ote": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "On-target earnings for the period, e.g. 30000; use with base_salary to derive target variable pay = OTE - base salary."
},
"name": {
"type": "string",
"maxLength": 60,
"description": "Plan label, e.g. \"AE plan FY26\" or \"Plan A\"."
},
"rate": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Flat commission rate in percent, e.g. 10 for 10%. With tiers that use multipliers this is the base commission rate."
},
"quota": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Quota for the period in currency, e.g. 150000. Used for attainment and quota-percent tiers."
},
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Commission rate for this tier in percent, e.g. 8 for 8%."
},
"up_to": {
"anyOf": [
{
"type": "number",
"maximum": 100000000000,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Upper limit of this tier, inclusive, in currency (e.g. 50000) or in percent of quota when tier_unit is quota_percent (e.g. 100). Leave null on the last, open-ended tier."
},
"multiplier": {
"anyOf": [
{
"type": "number",
"maximum": 20,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Instead of a rate: a multiple of the base commission rate, e.g. 1.5 for an accelerator above quota or 0.5 for a decelerator below 50% of quota."
}
}
},
"maxItems": 12,
"description": "Tiered rates in ascending order. \"5% up to 50k then 8% above\" = [{\"up_to\":50000,\"rate\":5},{\"up_to\":null,\"rate\":8}]. Accelerator over quota with tier_unit quota_percent: [{\"up_to\":100,\"rate\":10},{\"up_to\":null,\"rate\":15}]."
},
"bonuses": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"amount"
],
"properties": {
"label": {
"type": "string",
"maxLength": 80,
"description": "Bonus or SPIFF name, e.g. \"Q3 new-logo SPIFF\"."
},
"amount": {
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000,
"description": "Amount, e.g. 500."
}
}
},
"maxItems": 20,
"description": "One-off bonuses or SPIFFs for the period, outside tiers and the cap, e.g. [{\"label\":\"President's club SPIFF\",\"amount\":1000}]."
},
"draw_type": {
"enum": [
"recoverable",
"non_recoverable"
],
"type": "string",
"description": "recoverable (default: a shortfall carries forward and is repaid from later commission) or non_recoverable (the shortfall is forgiven, not repaid)."
},
"tier_unit": {
"enum": [
"amount",
"quota_percent"
],
"type": "string",
"description": "Tier limits in currency (amount, default) or in percent of quota attainment (quota_percent, needs quota)."
},
"cap_amount": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Maximum commission on deals for the period, e.g. 25000. SPIFFs and bonuses are outside the cap."
},
"base_salary": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Base salary for the same period as ote, e.g. 15000."
},
"draw_amount": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Draw against commission paid for the period, e.g. 3000."
},
"tier_method": {
"enum": [
"marginal",
"retroactive"
],
"type": "string",
"description": "marginal (stepped: each slice of sales at its own tier rate) or retroactive (all sales at the rate of the highest tier reached). Leave out when the plan wording does not say; both results are then shown."
},
"commission_base": {
"enum": [
"revenue",
"gross_margin"
],
"type": "string",
"description": "What the rate applies to: revenue (deal amount, default) or gross_margin (each deal's margin or margin_percent)."
},
"target_variable": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Target variable (incentive) pay at 100% of quota for the period, e.g. 15000. With quota it sets the base commission rate = target_variable / quota."
},
"clawback_percent": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Share of the original commission clawed back, in percent, default 100."
},
"clawback_window_days": {
"type": "integer",
"maximum": 3650,
"minimum": 0,
"description": "Days after close in which a refund or cancellation claws back commission, e.g. 90. Leave out to claw back any cancellation."
},
"unknown_status_as_won": {
"type": "boolean",
"description": "Count deals whose status is not recognised (e.g. \"Signed - pending\") as closed-won. Default false: they are listed as not counted."
}
},
"description": "Second plan, e.g. {\"name\":\"Accelerated\",\"quota\":100000,\"tier_unit\":\"quota_percent\",\"tiers\":[{\"up_to\":100,\"rate\":8},{\"up_to\":null,\"rate\":14}]}."
},
"currency": {
"type": "string",
"maxLength": 3,
"description": "ISO currency code, default USD, e.g. CAD or EUR."
},
"sales_levels": {
"type": "array",
"items": {
"type": "number",
"maximum": 100000000000,
"minimum": 0
},
"maxItems": 12,
"description": "Sales totals to compare at, e.g. [50000, 100000, 150000]. Default: 50% to 200% of the quota."
}
}
}Use this when the user wants commission statements for several reps, asks "how much commission did each rep earn this month", or attaches a deals export (CSV or Excel from a CRM or spreadsheet with rep, deal, amount, margin, close date, status columns; columns are matched automatically). Applies one plan to all reps (with per-rep quota, draw and prior balance overrides), handles split deals, SPIFFs, clawbacks, caps and draws, and returns a team summary, a commission statement PDF with one section per rep, and an Excel workbook listing each deal line. Does not compute taxes, withholding or take-home pay, and does not read PDF or image files. Do not use for a single quick commission question (use calculate_commission).
| Argument | Type | Description |
|---|---|---|
| file | object | The deals export to read, CSV or Excel (.xlsx), e.g. september-deals.csv, with one deal per row. |
| plan* | object | One plan applied to all reps (per-rep quota, draw and balance go in rep_overrides), e.g. {"rate":8,"clawback_window_days":90}. |
| deals | array | Typed deals when there is no file, each with rep (or splits), e.g. [{"rep":"Ana","deal":"Acme","amount":30000},{"deal":"Globex","amount":20000,"splits":[{"rep":"Ana","percent":60},{"rep":"Ben","percent":40}]}]. |
| currency | string | ISO currency code, default USD, e.g. CAD or EUR. |
| rep_name | string | Rep to credit when the file has no rep column, e.g. "Maria Lopez". |
| column_map | object | Only if automatic matching picks the wrong column: file header per field, e.g. {"amount":"Net Revenue","rep":"Opportunity Owner"}. |
| period_end | string | Last day of the period, e.g. 2026-09-30. |
| sheet_name | string | Excel sheet to read, e.g. "Closed Won". Default: the first sheet with an amount column. |
| company_name | string | Company name printed on the statements, e.g. "Acme Corp". |
| period_label | string | Label printed on statements, e.g. "September 2026" or "Q3 2026". |
| period_start | string | First day of the commission period, e.g. 2026-09-01. Deals closed outside the period are not counted. |
| rep_overrides | array | Per-rep quota, target variable, draw or prior balance, e.g. [{"rep":"Ana","quota":120000,"draw_amount":2000}]. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"plan"
],
"properties": {
"file": {
"type": "object",
"required": [
"download_url",
"file_id"
],
"properties": {
"file_id": {
"type": "string",
"description": "ChatGPT file id, e.g. file_abc123."
},
"file_name": {
"type": "string",
"description": "Original file name if known, e.g. statement.pdf."
},
"mime_type": {
"type": "string",
"description": "Media type if known, e.g. application/pdf."
},
"download_url": {
"type": "string",
"description": "Temporary download link for the file, supplied by ChatGPT."
}
},
"description": "The deals export to read, CSV or Excel (.xlsx), e.g. september-deals.csv, with one deal per row."
},
"plan": {
"type": "object",
"properties": {
"ote": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "On-target earnings for the period, e.g. 30000; use with base_salary to derive target variable pay = OTE - base salary."
},
"name": {
"type": "string",
"maxLength": 60,
"description": "Plan label, e.g. \"AE plan FY26\" or \"Plan A\"."
},
"rate": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Flat commission rate in percent, e.g. 10 for 10%. With tiers that use multipliers this is the base commission rate."
},
"quota": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Quota for the period in currency, e.g. 150000. Used for attainment and quota-percent tiers."
},
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Commission rate for this tier in percent, e.g. 8 for 8%."
},
"up_to": {
"anyOf": [
{
"type": "number",
"maximum": 100000000000,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Upper limit of this tier, inclusive, in currency (e.g. 50000) or in percent of quota when tier_unit is quota_percent (e.g. 100). Leave null on the last, open-ended tier."
},
"multiplier": {
"anyOf": [
{
"type": "number",
"maximum": 20,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Instead of a rate: a multiple of the base commission rate, e.g. 1.5 for an accelerator above quota or 0.5 for a decelerator below 50% of quota."
}
}
},
"maxItems": 12,
"description": "Tiered rates in ascending order. \"5% up to 50k then 8% above\" = [{\"up_to\":50000,\"rate\":5},{\"up_to\":null,\"rate\":8}]. Accelerator over quota with tier_unit quota_percent: [{\"up_to\":100,\"rate\":10},{\"up_to\":null,\"rate\":15}]."
},
"bonuses": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"amount"
],
"properties": {
"label": {
"type": "string",
"maxLength": 80,
"description": "Bonus or SPIFF name, e.g. \"Q3 new-logo SPIFF\"."
},
"amount": {
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000,
"description": "Amount, e.g. 500."
}
}
},
"maxItems": 20,
"description": "One-off bonuses or SPIFFs for the period, outside tiers and the cap, e.g. [{\"label\":\"President's club SPIFF\",\"amount\":1000}]."
},
"draw_type": {
"enum": [
"recoverable",
"non_recoverable"
],
"type": "string",
"description": "recoverable (default: a shortfall carries forward and is repaid from later commission) or non_recoverable (the shortfall is forgiven, not repaid)."
},
"tier_unit": {
"enum": [
"amount",
"quota_percent"
],
"type": "string",
"description": "Tier limits in currency (amount, default) or in percent of quota attainment (quota_percent, needs quota)."
},
"cap_amount": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Maximum commission on deals for the period, e.g. 25000. SPIFFs and bonuses are outside the cap."
},
"base_salary": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Base salary for the same period as ote, e.g. 15000."
},
"draw_amount": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Draw against commission paid for the period, e.g. 3000."
},
"tier_method": {
"enum": [
"marginal",
"retroactive"
],
"type": "string",
"description": "marginal (stepped: each slice of sales at its own tier rate) or retroactive (all sales at the rate of the highest tier reached). Leave out when the plan wording does not say; both results are then shown."
},
"commission_base": {
"enum": [
"revenue",
"gross_margin"
],
"type": "string",
"description": "What the rate applies to: revenue (deal amount, default) or gross_margin (each deal's margin or margin_percent)."
},
"target_variable": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Target variable (incentive) pay at 100% of quota for the period, e.g. 15000. With quota it sets the base commission rate = target_variable / quota."
},
"clawback_percent": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Share of the original commission clawed back, in percent, default 100."
},
"clawback_window_days": {
"type": "integer",
"maximum": 3650,
"minimum": 0,
"description": "Days after close in which a refund or cancellation claws back commission, e.g. 90. Leave out to claw back any cancellation."
},
"unknown_status_as_won": {
"type": "boolean",
"description": "Count deals whose status is not recognised (e.g. \"Signed - pending\") as closed-won. Default false: they are listed as not counted."
}
},
"description": "One plan applied to all reps (per-rep quota, draw and balance go in rep_overrides), e.g. {\"rate\":8,\"clawback_window_days\":90}."
},
"deals": {
"type": "array",
"items": {
"type": "object",
"required": [
"amount"
],
"properties": {
"rep": {
"type": "string",
"maxLength": 80,
"description": "Sales rep credited with the deal, e.g. \"Maria Lopez\"."
},
"deal": {
"type": "string",
"maxLength": 120,
"description": "Deal, customer or invoice name, e.g. \"Acme renewal\"."
},
"spiff": {
"anyOf": [
{
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000
},
{
"type": "null"
}
],
"description": "SPIFF paid on this deal, e.g. 250 (outside tiers and cap; split with the deal)."
},
"amount": {
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000,
"description": "Deal amount (revenue) in currency, e.g. 24000. Negative = credit or adjustment."
},
"margin": {
"anyOf": [
{
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000
},
{
"type": "null"
}
],
"description": "Gross margin amount of the deal, e.g. 7200 (for gross_margin plans)."
},
"splits": {
"type": "array",
"items": {
"type": "object",
"required": [
"rep",
"percent"
],
"properties": {
"rep": {
"type": "string",
"maxLength": 80,
"description": "Rep name, e.g. \"Dan Kim\"."
},
"percent": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Share in percent, e.g. 40."
}
}
},
"maxItems": 10,
"description": "Split between reps instead of rep, e.g. [{\"rep\":\"Ana\",\"percent\":60},{\"rep\":\"Ben\",\"percent\":40}]."
},
"status": {
"anyOf": [
{
"type": "string",
"maxLength": 40
},
{
"type": "null"
}
],
"description": "Deal status, e.g. won (default), refunded, cancelled, churned, chargeback, lost, open. Cancelled deals are clawed back; lost and open deals are not counted."
},
"close_date": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
],
"description": "Close date, e.g. 2026-09-14 or 9/14/2026 (US order). Sets the order in which deals fill tiers."
},
"cancel_date": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
],
"description": "Refund or cancellation date for the clawback window, e.g. 2026-10-20."
},
"split_percent": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": 0
},
{
"type": "null"
}
],
"description": "This rep's share of the deal in percent, e.g. 60 for a 60/40 split. Default 100."
},
"margin_percent": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": -100
},
{
"type": "null"
}
],
"description": "Gross margin in percent of the amount, e.g. 30 (alternative to margin)."
},
"commission_paid": {
"anyOf": [
{
"type": "number",
"maximum": 100000000000,
"minimum": -100000000000
},
{
"type": "null"
}
],
"description": "For a refunded deal from an earlier period: commission already paid on it, e.g. 1200. The clawback uses this amount."
}
}
},
"maxItems": 2000,
"description": "Typed deals when there is no file, each with rep (or splits), e.g. [{\"rep\":\"Ana\",\"deal\":\"Acme\",\"amount\":30000},{\"deal\":\"Globex\",\"amount\":20000,\"splits\":[{\"rep\":\"Ana\",\"percent\":60},{\"rep\":\"Ben\",\"percent\":40}]}]."
},
"currency": {
"type": "string",
"maxLength": 3,
"description": "ISO currency code, default USD, e.g. CAD or EUR."
},
"rep_name": {
"type": "string",
"maxLength": 80,
"description": "Rep to credit when the file has no rep column, e.g. \"Maria Lopez\"."
},
"column_map": {
"type": "object",
"properties": {
"rep": {
"type": "string",
"maxLength": 80,
"description": "Header of the rep column, e.g. \"Deal Owner\"."
},
"deal": {
"type": "string",
"maxLength": 80,
"description": "Header of the deal column, e.g. \"Opportunity Name\"."
},
"spiff": {
"type": "string",
"maxLength": 80,
"description": "Header of the spiff column, e.g. \"SPIFF\"."
},
"amount": {
"type": "string",
"maxLength": 80,
"description": "Header of the amount column, e.g. \"Amount\"."
},
"margin": {
"type": "string",
"maxLength": 80,
"description": "Header of the margin column, e.g. \"Gross Profit\"."
},
"status": {
"type": "string",
"maxLength": 80,
"description": "Header of the status column, e.g. \"Stage\"."
},
"close_date": {
"type": "string",
"maxLength": 80,
"description": "Header of the close date column, e.g. \"Close Date\"."
},
"cancel_date": {
"type": "string",
"maxLength": 80,
"description": "Header of the cancel date column, e.g. \"Cancel Date\"."
},
"split_percent": {
"type": "string",
"maxLength": 80,
"description": "Header of the split percent column, e.g. \"Split %\"."
},
"margin_percent": {
"type": "string",
"maxLength": 80,
"description": "Header of the margin percent column, e.g. \"GM %\"."
},
"commission_paid": {
"type": "string",
"maxLength": 80,
"description": "Header of the commission paid column, e.g. \"Commission Paid\"."
}
},
"description": "Only if automatic matching picks the wrong column: file header per field, e.g. {\"amount\":\"Net Revenue\",\"rep\":\"Opportunity Owner\"}."
},
"period_end": {
"type": "string",
"maxLength": 30,
"description": "Last day of the period, e.g. 2026-09-30."
},
"sheet_name": {
"type": "string",
"maxLength": 60,
"description": "Excel sheet to read, e.g. \"Closed Won\". Default: the first sheet with an amount column."
},
"company_name": {
"type": "string",
"maxLength": 80,
"description": "Company name printed on the statements, e.g. \"Acme Corp\"."
},
"period_label": {
"type": "string",
"maxLength": 60,
"description": "Label printed on statements, e.g. \"September 2026\" or \"Q3 2026\"."
},
"period_start": {
"type": "string",
"maxLength": 30,
"description": "First day of the commission period, e.g. 2026-09-01. Deals closed outside the period are not counted."
},
"rep_overrides": {
"type": "array",
"items": {
"type": "object",
"required": [
"rep"
],
"properties": {
"rep": {
"type": "string",
"maxLength": 80,
"description": "Rep name as it appears in the deals, e.g. \"Maria Lopez\"."
},
"quota": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "This rep's quota for the period, e.g. 120000."
},
"draw_amount": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "This rep's draw for the period, e.g. 2500."
},
"prior_balance": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "Unrecovered draw or clawback balance this rep still owes from earlier periods, e.g. 800."
},
"target_variable": {
"type": "number",
"maximum": 100000000000,
"minimum": 0,
"description": "This rep's target variable pay, e.g. 12000."
}
}
},
"maxItems": 200,
"description": "Per-rep quota, target variable, draw or prior balance, e.g. [{\"rep\":\"Ana\",\"quota\":120000,\"draw_amount\":2000}]."
}
}
}