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

# Commissions API

> Read and change Orbit CRM commissions from code or an AI agent: the Commissions settings, plans and the people on them, statements, approvals and payouts, adjustments, objective scores, disputes, and who earns what on a deal. A credential sees and changes only what its owner can in Orbit.

Orbit calculates sales commissions from the deals and activity already in your workspace. A **plan** sets the rules (quotas and how people earn), people are **on a plan** from a date, and each person gets one **statement** per plan per period (month, quarter or year). A statement is **open** while it is calculated live, **approved** once a manager locks it, and **paid** once the payout is recorded.

This API covers everything the Commissions page and settings do: build plans, put people on them, read statements, approve and record payouts, add adjustments, score objectives, handle disputes and split a deal's commission. The same endpoints power the commission tools of the [MCP server](https://docs.useorbitcrm.ai/mcp/tools.md).

> [!WARNING]
>
> **Orbit never pays anyone.** Marking a statement paid records that it was paid (the date and an optional reference). Payroll happens outside Orbit.

## Scopes

| Scope | Allows |
| - | - |
| `commissions:read` | Read the settings, plans, people on plans, templates, statements, adjustments, disputes and a deal's commission, and preview a plan. Only what the credential's owner can see in Orbit. Statement lines and a deal's commission show the names, values, status and owners of the deals behind them, without `deals:read` |
| `commissions:write` | Change the settings; create, change, archive and delete plans and the people on them; approve, mark paid and reopen statements; apply corrections; add and delete adjustments; score objectives; raise and resolve disputes; set a deal's split and custom commissions. Each still needs the owner's permission (below): a deal's primary owner can change its split without Manage commissions |

A credential whose owner is a **Viewer** can hold read scopes only, so it can't write here. The **CRM agent** API key preset in [Settings → API keys](https://app.useorbitcrm.ai/settings/api-keys) includes both commission scopes.

## Who sees and does what

A credential acts as the person who created it (the API key's owner, or the person who connected the app). Every answer is the one that person gets in Orbit:

* **Commissions are on in every workspace.** There is nothing to turn on: create a plan and put people on it. A workspace can turn commissions off with `PATCH /settings` (`enabled: false`). While they are off, every endpoint except `settings` answers `409 commissions_off`, until someone with Manage commissions sends `enabled: true`.
* **Reading** shows the owner's own statements, the statements of people who report to them (directly or through others, from Settings → Team), and everyone's if their role has **View all commissions**. Someone who is on no plan, has no reports and can't view all commissions gets `403 permission_denied`.
* **Changing** anything needs **Manage commissions**: the workspace owner always has it, the built-in Admin role has it, and a custom role can be given it. Two exceptions:
  * Anyone on a plan can **dispute** a line on their own statement.
  * A deal's **primary owner** can **split** its commission between its owners, while the `owners_can_split` setting is on.
* **Someone you can't see is answered like someone who doesn't exist.** One record you can't see is a `404 not_found`, the same answer as an id that doesn't exist. Lists leave it out.

`GET /api/v1/commissions/settings` returns the owner's `access` with the settings, so an integration can check what it may do before it tries.

## Errors

Errors have the standard API shape:

```json theme={null}
{ "error": "commissions_off", "error_description": "Commissions are off in this workspace." }
```

| Status | `error` | When |
| - | - | - |
| `400` | `invalid_request` | The body is not a JSON object, a query parameter or field is invalid (`error_description` names it), or `items` lists fewer than 1 or more than 100 statements. Dates and period starts are real calendar dates from 2000 to 2099: `2026-02-30`, `2026-13-01` and `9999-12-01` are refused |
| `401` | `unauthorized`, `invalid_token` | The API key or access token is missing, expired or revoked |
| `403` | `insufficient_scope` | The credential lacks `commissions:read` or `commissions:write`. The `WWW-Authenticate` header names the scope |
| `403` | `permission_denied` | The owner's role doesn't allow it: Manage commissions for changes, or nothing to see for reads |
| `403` | `forbidden` | A write from a Viewer's credential, or the owner left the workspace |
| `404` | `not_found` | No such plan, person on a plan, statement, adjustment, dispute or deal, or the owner can't see it |
| `422` | `invalid_request` | Well formed, but not possible here: an adjustment for someone not on that plan in that period, a dispute on a period that hasn't started, or a deal split naming someone who doesn't own the deal |
| `409` | `commissions_off` | This workspace turned commissions off |
| `409` | `conflict` | The change clashes with what is stored, for example a person already on the plan for overlapping dates, or a plan with locked statements going back to draft |
| `409` | `limit_reached` | A workspace already has 200 plans, or a plan 500 people |
| `409` | `statement_locked` | An adjustment or objective score for an approved or paid statement (also one approved while the request was being saved: nothing is kept): reopen it first |
| `413` | `too_many_rows` | More statements than one answer holds: narrow it with `plan_id` or `user_id` |
| `413` | `invalid_request` | The body is larger than the endpoint takes (16 KB for the settings and a deal's split; 32 KB for statements, corrections, adjustments, objective scores and disputes; 64 KB for a person on a plan; 256 KB for a plan; 768 KB for a preview) |
| `429` | `rate_limit_exceeded` | Too many requests; wait for `Retry-After` seconds. `POST /preview` has its own limit of 20 a minute |

## Endpoints

All paths start with `https://app.useorbitcrm.ai/api/v1/commissions`. Ids are UUIDs and dates are `YYYY-MM-DD`.

| Method | Endpoint | Scope | Who | Description |
| - | - | - | - | - |
| `GET` | `/settings` | read | Any member | `{ settings, access }`. Also answers in a workspace that turned commissions off |
| `PATCH` | `/settings` | write | Manage | Change any of the [settings](#settings). Also answers in a workspace that turned commissions off |
| `GET` | `/plans` | read | Can see | The plans, by name, with the people on them |
| `POST` | `/plans` | write | Manage | Create a [plan](#plans) → `201` |
| `GET` | `/plans/:id` | read | Can see | One plan |
| `PATCH` | `/plans/:id` | write | Manage | Change any of the plan's fields |
| `DELETE` | `/plans/:id` | write | Manage | Delete the plan, or archive it when someone has an approved or paid statement on it |
| `GET` | `/plans/:id/members` | read | Can see | The [people on the plan](#people-on-a-plan) |
| `POST` | `/plans/:id/members` | write | Manage | Put someone on the plan → `201` |
| `PATCH` | `/plans/:id/members/:memberId` | write | Manage | Change their dates or their own numbers |
| `DELETE` | `/plans/:id/members/:memberId` | write | Manage | Take them off the plan |
| `GET` | `/templates` | read | Can see | Ready-made plans to start from |
| `POST` | `/preview` | read | Can see | [Calculate a plan](#preview) on example deals and activity. Stores nothing |
| `GET` | `/statements` | read | Can see | [Statement](#statements) summaries for a period (`date`, `plan_id`, `user_id`) |
| `GET` | `/statement` | read | Can see | One statement with its lines (`plan_id`, `user_id` and `period_start`, all required) |
| `POST` | `/statements/approve` | write | Manage | Lock statements as they calculate now |
| `POST` | `/statements/pay` | write | Manage | Record statements as paid |
| `POST` | `/statements/reopen` | write | Manage | Unlock approved, unpaid statements |
| `POST` | `/corrections` | write | Manage | Add a locked statement's difference to the current period, or keep the approved amount |
| `GET` | `/adjustments` | read | Can see | A period's [adjustments](#adjustments) (`period_start` required; `plan_id`, `user_id`) |
| `POST` | `/adjustments` | write | Manage | Add a one-off amount with a note → `201` |
| `DELETE` | `/adjustments/:id` | write | Manage | Delete an adjustment |
| `PUT` | `/mbo-scores` | write | Manage | Score a person's [objectives](#objective-scores) for a period |
| `GET` | `/disputes` | read | Can see | [Disputes](#disputes) (`status`: `open` or `resolved`; `plan_id`, `user_id`, `period_start`) |
| `POST` | `/disputes` | write | On a plan | Dispute a line on your own statement → `201` |
| `PATCH` | `/disputes/:id` | write | Manage | Resolve a dispute, or reopen it |
| `GET` | `/deals/:id` | read | Can see, and can see the deal | [Who earns what on a deal](#a-deals-commission), with its split |
| `GET` | `/deals/:id/split` | read | Can see, and can see the deal | The deal's [commission split](#a-deals-commission-split) |
| `PUT` | `/deals/:id/split` | write | Manage, or the primary owner | Set the deal's split |

**Can see** means the owner is on a plan, has people reporting to them, or can view all commissions. What each answer contains is then limited to the people they can see.

## Settings

| Setting | Type | Default | What it does |
| - | - | - | - |
| `enabled` | boolean | `true` | Commissions are on. `false` turns them off for the whole workspace: nothing is calculated and nobody sees them, and plans and statements are kept |
| `approvals` | boolean | `true` | Statements are approved, then paid. When off, marking a statement paid also locks it |
| `time_zone` | IANA time zone | `UTC` | Periods and the days deals and activity count on follow it, e.g. `America/New_York`. Set it before you create the first plan |
| `default_split` | `primary` \| `even` | `primary` | A deal with co-owners and no split of its own pays its primary owner (`primary`) or its owners evenly (`even`) |
| `owners_can_split` | boolean | `true` | A deal's primary owner may split its commission between the deal's owners |

`GET /settings` answers `{ data: { settings, access } }`:

```json theme={null}
{
  "data": {
    "settings": { "enabled": true, "approvals": true, "time_zone": "America/New_York", "default_split": "primary", "owners_can_split": true, "updated_at": "2026-11-19T15:02:11Z" },
    "access": {
      "enabled": true,
      "approvals": true,
      "can_manage": false,
      "can_view_all": false,
      "viewer_id": "7c1f…",
      "reports": ["a91e…", "d03b…"],
      "on_plan": true,
      "can_see_anything": true
    }
  }
}
```

`access` says what the credential's owner can do: `can_manage` (Manage commissions), `can_view_all` (View all commissions, or Manage), `reports` (the people whose statements they see as a manager), `on_plan` (they are on a plan that isn't a draft) and `can_see_anything`.

`PATCH /settings` takes any of the settings and answers them all. Only the settings you send change, and unknown keys are refused (`400`). `time_zone` is an IANA name such as `Europe/London`, never an offset.

```bash theme={null}
curl -X PATCH https://app.useorbitcrm.ai/api/v1/commissions/settings \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "time_zone": "America/New_York", "default_split": "even" }'
```

## Plans

```json theme={null}
{
  "id": "5b0e…",
  "name": "Account executives 2027",
  "description": "10% to quota, 15% past it",
  "status": "active",
  "period": "quarter",
  "starts_on": "2027-01-01",
  "ends_on": null,
  "definition": { "credit": "splits", "earn_on": { "kind": "won_date" }, "clawback_days": 90, "quotas": [], "components": [] },
  "member_count": 6,
  "members": [{ "id": "c4d2…", "plan_id": "5b0e…", "user_id": "a91e…", "starts_on": "2027-01-01", "ends_on": null, "settings": {} }],
  "created_at": "2026-11-19T15:02:11Z",
  "updated_at": "2026-11-19T15:02:11Z"
}
```

Every plan answer carries `members`, the people on it the credential's owner can see. The list leaves out their `settings`; one plan, a create and an update include them.

| Field | What it is |
| - | - |
| `name` | 1 to 80 characters |
| `description` | Up to 1,000 characters, or `null` |
| `status` | `draft` (being set up; nobody earns), `active` (earning) or `archived` (kept for history). A new plan is a `draft` unless you say otherwise |
| `period` | `month`, `quarter` or `year`. Quarters and years follow the workspace's fiscal year (Settings → Deals) |
| `starts_on`, `ends_on` | The first and last day the plan can earn on. `ends_on` is `null` for no end |
| `definition` | The rules, below |

Who sees which plans: someone with Manage or View all commissions sees every plan. Anyone else sees the plans they are on (never a draft), and on each only themselves and the people who report to them. `member_count` always counts everyone on the plan.

Changing a plan changes open statements at once. Locked (approved or paid) statements never change; one that would now calculate differently shows a correction (see [Corrections](#corrections)).

`DELETE` deletes a plan, or archives it when someone has an approved or paid statement on it: those statements are never deleted. It answers `{ "id": "5b0e…", "outcome": "deleted" }` or `"outcome": "archived"`. To archive a plan without deleting it, send `PATCH` with `{ "status": "archived" }`. A plan with approved or paid statements can't go back to `draft` (`409 conflict`). A workspace can have up to 200 plans (`409 limit_reached`).

### The rules (`definition`)

| Field | What it is |
| - | - |
| `credit` | Who a won deal credits. `splits` (the default): the deal's own [commission split](#a-deals-commission-split), else its deal splits, else the workspace `default_split`. `owner`: the primary owner only. `all_owners`: the primary owner and every co-owner, each in full. `shared_owners`: the owners share it evenly. `everyone`: every person on the plan, in full. `creator`: whoever created the deal, in full (SDRs paid on the deals they sourced) |
| `earn_on` | When a deal counts: `{ "kind": "won_date" }`, or a date field on the deal, `{ "kind": "date_field", "field": "cf:invoice_paid_on" }` |
| `clawback_days` | A paid deal that is lost, reopened or deleted within this many days is taken back in the current period. `null`: never |
| `product_keys` | Optional. Only deals and activity on these workspace products count |
| `max_per_period` | Optional. The most the plan pays a person per period |
| `quotas` | Up to 10 targets per period, each `{ id, name, measure, target, scope?, from_goals?, cumulative? }` |
| `components` | Up to 30 ways of earning (below) |

A **measure** says what is counted: `{ "source": "deals", "value": { "kind": "amount" }, "filter": { … } }` for deals, or `{ "source": "activity", "activity": "meeting_booked", "filter": { … } }` for activity. Deal values: `amount`, `count`, `recurring` (`per`: `month` or `year`), `line_items` and `field` (a number field). Activities: `meeting_booked`, `meeting_held`, `meeting_booked_on_call`, `live_call`, `call`, `deal_created` and `deal_won`. Filters narrow by pipeline, deal type, product, record team, line-item product, minimum value and field conditions (deals), or by scheduling page, call outcome and call length (activity).

Each component has a `type`, a stable `id` (`[a-z0-9_]`, up to 40 characters) and a `name`:

| `type` | Pays | Key fields |
| - | - | - |
| `rate` | A percent of deal value, flat or in tiers (accelerators, decelerators) | `measure` (deals), `tiers: [{ from, rate }]`, `tier_basis`: `attainment` (% of a quota), `total` (the period's running total) or `each_deal`; `quota_id`, `retroactive`, `multipliers`, `max_per_deal` |
| `per_unit` | A fixed amount per deal or activity, optionally tiered | `measure`, `tiers` (`rate` is the amount per unit, in money to the cent), `tier_basis`: `attainment` or `total` |
| `bonus` | A bonus on a quota | `quota_id`, `kind`: `target` (`target_amount` × attainment, `tiers` to speed it up) or `milestone` (`milestones: [{ at, amount }]`) |
| `mbo` | A target split over weighted objectives a manager scores | `target_amount`, `objectives: [{ id, name, weight }]`, `max_score` |
| `team_earnings` | A manager override: a percent of what their reports earned | `rate` |

Every component can also take `scope` (`{ "kind": "own" }`, or `{ "kind": "team" }` for a manager's roll-up), `active_from` / `active_to` (a SPIFF), `gate` (pay nothing until a quota reaches `min_attainment`: `cliff` or `hurdle`), `max_per_period` and `payout` (holdbacks: `[{ percent, when }]`, where `when` is `{ "kind": "earned" }`, `{ "kind": "days_after", "days": 90 }` or `{ "kind": "date_field", "field": "cf:payment_received" }`).

Rates are percents (`10` is 10%, up to 1,000). Amounts and targets are 0 to 1,000,000,000 in the workspace currency. A plan that breaks a rule is refused with `400 invalid_request` and a message that says where, e.g. `definition.components[1].tiers[0].rate: A rate is a percent from 0 to 1000`.

Create a plan that pays 10% of won deal amounts up to a \$250,000 quarterly quota and 15% past it:

```bash theme={null}
curl -X POST https://app.useorbitcrm.ai/api/v1/commissions/plans \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Account executives 2027",
    "period": "quarter",
    "starts_on": "2027-01-01",
    "status": "active",
    "definition": {
      "credit": "splits",
      "earn_on": { "kind": "won_date" },
      "clawback_days": 90,
      "quotas": [
        { "id": "revenue", "name": "Revenue", "measure": { "source": "deals", "value": { "kind": "amount" } }, "target": 250000 }
      ],
      "components": [
        {
          "id": "commission", "name": "Commission", "type": "rate",
          "measure": { "source": "deals", "value": { "kind": "amount" } },
          "tier_basis": "attainment", "quota_id": "revenue",
          "tiers": [{ "from": 0, "rate": 10 }, { "from": 100, "rate": 15 }]
        }
      ]
    }
  }'
```

`GET /templates` returns ready-made plans to start from: account executive (flat rate, accelerators, decelerators, cliff, cap, milestone bonus, contract-term multiplier), SDR (per meeting booked, per meeting booked on a call, per live call, per meeting held, qualified opportunities), account manager, sales manager (team roll-up, override), a SPIFF and a blank plan. Each is `{ key, name, role, description, plan: { period, definition }, asks? }`. Send `plan.period` and `plan.definition` to `POST /plans` as they are or changed. `asks` lists deal fields a template needs you to choose first, such as which number field holds the contract term: replace the placeholder `field` in the definition with your own.

## People on a plan

```json theme={null}
{ "id": "c4d2…", "plan_id": "5b0e…", "user_id": "a91e…", "starts_on": "2027-01-01", "ends_on": null, "settings": {} }
```

`POST /plans/:id/members` takes `{ user_id, starts_on?, ends_on?, settings? }`; `starts_on` defaults to the plan's. `PATCH` takes any of `starts_on`, `ends_on` and `settings` (to put someone else on the plan, remove this person and add them). `user_id` must be a member of the workspace. A person can be on a plan only once for any day (`409 conflict` for overlapping dates), an archived plan takes nobody new (`409 conflict`), and a plan holds up to 500 people (`409 limit_reached`). Their first period starts at the later of the plan's and their own `starts_on`. `GET` lists only the people the credential's owner can see.

`settings` holds a person's own numbers; anything left out uses the plan's:

| Field | What it is |
| - | - |
| `quotas` | Quota id → `{ target, by_period }`. `by_period` maps a period's first day to a target, for ramps: `{ "2027-01-01": 50000, "2027-04-01": 150000 }` |
| `tiers` | Component id → their own tiers |
| `target_amounts` | Component id → their own bonus or MBO target amount |
| `draw` | `{ "kind": "recoverable" \| "non_recoverable", "amount": 5000 }`: paid at least this much per period. A recoverable draw is paid back from later earnings above it |

## Preview

`POST /preview` runs a plan on example numbers and stores nothing: "what would a rep closing $120,000 against a $100,000 quota earn?" It reads only the workspace's currency, fiscal year, time zone and products.

```bash theme={null}
curl -X POST https://app.useorbitcrm.ai/api/v1/commissions/preview \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": { "period": "quarter", "definition": { "credit": "owner", "earn_on": { "kind": "won_date" }, "clawback_days": null, "quotas": [ { "id": "revenue", "name": "Revenue", "measure": { "source": "deals", "value": { "kind": "amount" } }, "target": 100000 } ], "components": [ { "id": "commission", "name": "Commission", "type": "rate", "measure": { "source": "deals", "value": { "kind": "amount" } }, "tier_basis": "attainment", "quota_id": "revenue", "tiers": [ { "from": 0, "rate": 10 }, { "from": 100, "rate": 15 } ] } ] } },
    "deals": [ { "name": "Acme", "amount": 90000 }, { "name": "Globex", "amount": 30000 } ]
  }'
```

| Field | What it is |
| - | - |
| `plan` | Required: `{ period, definition }`, a saved plan's or a new one |
| `settings` | Optional: a person's own numbers, as on [people on a plan](#people-on-a-plan) |
| `date` | Optional: a day in the period to preview (default today) |
| `deals` | Up to 500 example won deals: `{ name?, amount, earned_on?, deal_type?, pipeline_id?, fields?, credit? }`. `earned_on` is a day in the period (default its first day); `credit` is the share, 0 to 1 |
| `activities` | Up to 2,000 example activities: `{ kind, on?, outcome?, duration_seconds? }`, `on` a day in the period |
| `team_earnings` | Optional: what the person's reports earned, for a manager override |

It answers `{ period: { start, end }, earnings }`: `earnings` has the quotas, the lines (see [Statements](#statements)), `earned`, `held`, `payable_now`, `next_tier` and `warnings`. A plan or example that breaks a rule is a `400` that says which. The plan's `definition` can be as large as a saved plan's (128 KB). A preview costs more than a read, so it has a limit of its own: 20 a minute for each credential's owner (`429` past it).

## Statements

`GET /statements` returns a summary per person and plan for each plan's period that contains `date` (default: today in the commission time zone). `plan_id` and `user_id` narrow it. It answers `{ "data": [...], "today": "2027-02-03" }`: `today` is the day in the commission time zone, the one Orbit uses to tell whether a period is over.

Someone who is no longer on a plan (their time on it or the plan ended, or the plan was archived) still has a statement for a period in which something from their earlier approved statements lands: a held part that came due, a deal taken back, an adjustment or a correction. It has no earnings, only those lines, and is approved and paid like any other. Archived plans otherwise show only statements that were locked.

```json theme={null}
{
  "plan_id": "5b0e…",
  "plan_name": "Account executives 2027",
  "user_id": "a91e…",
  "period_start": "2027-01-01",
  "period_end": "2027-03-31",
  "status": "open",
  "earned": 26250,
  "payable": 26250,
  "attainment": 115,
  "correction_pending": null,
  "open_disputes": 0,
  "approved_at": null,
  "paid_at": null
}
```

`status` is `open` (calculated live), `approved` (locked) or `paid`. `attainment` is the first quota's, in %. `correction_pending` is the difference a locked statement would now show, or `null`.

`GET /statement?plan_id=&user_id=&period_start=` returns one statement: `{ summary, result, adjustments, disputes, approved_by, paid_by, paid_note }`. `period_start` is the period's first day (periods start on the 1st, so it is `YYYY-MM-01`). Someone the credential's owner can't see is a `404`, the same as a statement that doesn't exist.

`result` shows how it was calculated: `quotas` (target, actual and attainment for each), `lines`, `totals` (`earned`, `held`, `other`, `draw`, `payable`), `draw_balance`, `next_tier` (what it takes to reach the next rate) and `warnings`. Each line has a `key`, a `kind`, a `label`, the `amount` earned, `payable_now`, any `held` parts with when they are released, and a `detail` showing the working:

| `kind` | Line |
| - | - |
| `rate`, `per_unit`, `bonus`, `mbo`, `team_earnings` | Earned from a component |
| `custom` | A custom commission set on a deal for this person |
| `release` | A held part of an earlier period that is payable now. A held part is never released once its deal is no longer won |
| `clawback` | A paid deal that was lost, reopened or deleted within the plan's window, taken back (negative). The window runs from the day the deal was won to the day it first left a won stage |
| `adjustment`, `correction` | Added by a manager |
| `draw_topup`, `draw_recovery` | The draw paid up to its amount, or paid back |
| `cap` | What a cap took off (negative) |

Money is in the workspace currency, rounded to the cent per line.

### Approving, paying and reopening

The three endpoints take the same body, 1 to 100 statements at a time (repeats are counted once):

```bash theme={null}
curl -X POST https://app.useorbitcrm.ai/api/v1/commissions/statements/pay \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "plan_id": "5b0e…", "user_id": "a91e…", "period_start": "2027-01-01" },
      { "plan_id": "5b0e…", "user_id": "d03b…", "period_start": "2027-01-01" }
    ],
    "note": "January payroll, batch 14"
  }'
```

* `approve` locks each statement as it calculates now. Only a period that is over can be approved.
* `pay` records each as paid now, with `note` as the payment reference (up to 500 characters). With `approvals` on, a statement must be approved first; with them off, `pay` also locks it.
* `reopen` unlocks approved statements so they calculate live again. A paid statement never reopens. Nor does one while a later statement of the same person and plan is approved or paid (`later_periods_locked`: reopen the later periods first). Corrections that were applied from the statement are removed with it, because it will be approved again at what it then calculates.

Each statement is answered on its own, so one that can't change doesn't stop the rest. If one fails outright (an `internal_error`, not a refusal), the batch ends there: the answer still lists the statements before it, which stay changed, and the ones after it were not tried.

```json theme={null}
{
  "data": {
    "results": [
      { "plan_id": "5b0e…", "user_id": "a91e…", "period_start": "2027-01-01", "ok": true, "status": "paid" },
      { "plan_id": "5b0e…", "user_id": "d03b…", "period_start": "2027-01-01", "ok": false, "status": "open", "error": "not_approved", "message": "Approve this statement before marking it paid." }
    ]
  }
}
```

An item's `error` is one of `not_found`, `not_locked`, `already_approved`, `already_paid`, `not_approved`, `approvals_off`, `period_not_over`, `later_periods_locked`, `correction_locked` (a correction from the statement is on an approved or paid statement: reopen that one first), `conflict` (it changed meanwhile: read it again and retry) or `internal_error` (it failed: the batch stopped there). The person is told when their statement is approved or paid.

### Corrections

A locked statement that would now calculate differently (a deal changed, a plan was edited) shows the difference as `correction_pending`. `POST /corrections` takes `{ "action": "apply" | "keep", "plan_id", "user_id", "period_start" }`. `apply` adds the difference as a `correction` adjustment to the person's current period on that plan, or the next one that isn't locked; `keep` keeps the approved amount and stops showing it. It answers `{ action, amount, adjustment }`.

## Adjustments

A one-off amount with a note, added to a person's statement for a period:

```json theme={null}
{ "id": "e81a…", "plan_id": "5b0e…", "user_id": "a91e…", "period_start": "2027-01-01", "amount": -250, "note": "Refund on the Acme deal", "kind": "manual", "created_by": "7c1f…", "created_at": "2027-01-20T10:00:00Z" }
```

* `GET /adjustments?period_start=` lists a period's adjustments for the people the credential's owner can see; `period_start` is required, and `plan_id` and `user_id` narrow it.
* `POST /adjustments` takes `{ user_id, plan_id?, period_start, amount, note }` and answers `201`. `amount` is not zero, up to 1,000,000,000 either way, to the cent; `note` is 1 to 500 characters. Without `plan_id` it lands on the person's first plan with a period starting that day. The person must be on the plan in that period, and `period_start` must start one of its periods (`422 invalid_request` otherwise).
* `DELETE /adjustments/:id` answers `{ "deleted": true }`.

Adjustments change only open statements: on an approved or paid one, both answer `409 statement_locked` (reopen it first). `kind` is `correction` for one made by `POST /corrections`.

## Objective scores

For plans with an `mbo` component, `PUT /mbo-scores` sets a person's objective scores for a period, in %:

```json theme={null}
{
  "plan_id": "5b0e…",
  "user_id": "a91e…",
  "period_start": "2027-01-01",
  "scores": [
    { "component_id": "objectives", "objective_id": "pipeline_hygiene", "score": 90 },
    { "component_id": "objectives", "objective_id": "certification", "score": null }
  ]
}
```

Send up to 300 scores at a time. A score is a percent from 0 to 1,000, to two decimals, and `null` clears it; the plan counts each up to the component's `max_score` (100 by default), and a missing score as 0. It answers `{ saved, cleared }`. Like adjustments, scores change open statements only (`409 statement_locked` otherwise), and the person must be on the plan in that period (`422`). A component or objective the plan doesn't have is a `422`.

## Disputes

A person on a plan can flag a line on their own statement; someone with Manage commissions resolves it. People with Manage commissions are told about a new dispute, and the person who raised it is told when it is resolved, with the resolution. A period that hasn't started can't be disputed (`422`).

```bash theme={null}
curl -X POST https://app.useorbitcrm.ai/api/v1/commissions/disputes \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan_id": "5b0e…", "period_start": "2027-01-01", "line_key": "commission:9f3c…", "note": "This deal should have paid 15%: we were past quota." }'
```

`note` is 1 to 2,000 characters; `line_key` (a line's `key`) and `deal_id` are optional. A dispute is always on the credential owner's own statement: sending someone else's `user_id` is a `403`, managers included. It answers `201` with the dispute: `{ id, plan_id, user_id, period_start, line_key, deal_id, note, status, resolution, created_by, created_at, resolved_by, resolved_at }`.

`GET /disputes` lists the disputes on statements the credential's owner can see, newest first; `status` (`open` or `resolved`), `plan_id`, `user_id` and `period_start` narrow it. `PATCH /disputes/:id` with `{ "status": "resolved", "resolution": "Rate corrected; the difference is on February" }` resolves one (a resolution is required, up to 2,000 characters); `{ "status": "open" }` reopens it.

## A deal's commission

`GET /deals/:id` answers who earns what on a deal: for a won deal, what each person's statement pays on it; for an open deal, about what each would earn if it were won today (`estimated: true`). It lists only the people the credential's owner can see, and includes the deal's split. A deal the owner can't see in Orbit (their record access, or a pipeline hidden from them) is a `404`, the same as a deal that doesn't exist.

```json theme={null}
{
  "data": {
    "deal_id": "9f3c…",
    "deal_status": "won",
    "people": [
      { "user_id": "a91e…", "plan_id": "5b0e…", "plan_name": "Account executives 2027", "period_start": "2027-01-01", "period_end": "2027-03-31", "amount": 4200, "estimated": false, "status": "open", "lines": [] }
    ],
    "warnings": [],
    "split": { "deal_id": "9f3c…", "mode": "primary", "shares": [], "custom_pay": [], "stale": false, "updated_by": null, "updated_at": null },
    "owners": ["a91e…", "d03b…"],
    "default_split": "primary",
    "can_edit": "all"
  }
}
```

`warnings` says when someone can't be paid, e.g. a custom commission for a person on no active plan ("Add Bob to a plan to pay this").

## A deal's commission split

By default a deal's commission goes to its primary owner (or to its owners evenly, if the workspace `default_split` is `even`). A deal's split changes that for one deal, for plans that credit by the deal's split (`credit: "splits"`, the default):

| `mode` | Who gets the deal's commission |
| - | - |
| `primary` | The primary owner |
| `even` | Whoever owns the deal (primary owner and co-owners), evenly. Adding a co-owner later re-splits |
| `custom` | The `shares` you set: a percent per owner (0.01 to 100), adding up to exactly 100 |

`custom_pay` gives an owner a **custom commission** on this deal instead of what their plans pay on it: a fixed `amount` (0 to 1,000,000,000), or a `rate` in % of the deal's whole amount (0 to 100). Their share still counts toward their quota. Custom commissions apply under every credit rule and are paid once, on one of the person's active plans.

`GET /deals/:id/split` answers:

```json theme={null}
{
  "data": {
    "split": {
      "deal_id": "9f3c…",
      "mode": "custom",
      "shares": [{ "user_id": "a91e…", "percent": 70 }, { "user_id": "d03b…", "percent": 30 }],
      "custom_pay": [],
      "stale": false,
      "updated_by": "7c1f…",
      "updated_at": "2027-01-12T09:30:00Z"
    },
    "owners": ["a91e…", "d03b…"],
    "default_split": "primary",
    "can_edit": "split"
  }
}
```

`owners` lists the deal's owners now, the primary owner first. `can_edit` says what the credential's owner may change: `all` (Manage commissions), `split` (the deal's primary owner while `owners_can_split` is on: `mode` and `shares`, not `custom_pay`) or `none`. A deal with no split of its own shows the workspace default. If a split names someone who no longer owns the deal, `stale` is `true` and the deal uses the workspace default until the split is set again.

`PUT /deals/:id/split` sets the split: send `mode`, `shares` with `custom`, and `custom_pay` to change the custom commissions (leave it out to keep them as they are; `[]` removes them). Shares and custom commissions can name only the deal's current owners. It answers like `GET`.

Split it evenly between the owners:

```bash theme={null}
curl -X PUT https://app.useorbitcrm.ai/api/v1/commissions/deals/9f3c…/split \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "even" }'
```

70% to the primary owner, 30% to a co-owner:

```bash theme={null}
curl -X PUT https://app.useorbitcrm.ai/api/v1/commissions/deals/9f3c…/split \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "custom", "shares": [{ "user_id": "a91e…", "percent": 70 }, { "user_id": "d03b…", "percent": 30 }] }'
```

Keep the commission with the primary owner, and pay a co-owner a custom commission of \$500 on this deal (Manage commissions only):

```bash theme={null}
curl -X PUT https://app.useorbitcrm.ai/api/v1/commissions/deals/9f3c…/split \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "primary", "custom_pay": [{ "user_id": "d03b…", "kind": "amount", "value": 500 }] }'
```

A rate is `{ "kind": "rate", "value": 5 }`: 5% of the deal's amount.

| Error | When |
| - | - |
| `400 invalid_request` | An unknown `mode`, shares that don't add up to 100, or a value out of range. The message says which |
| `422 invalid_request` | A share or custom commission names someone who doesn't own the deal |
| `403 permission_denied` | The credential's owner is neither a commission manager nor the deal's primary owner, the primary owner while `owners_can_split` is off, or the primary owner changing `custom_pay` |
| `404 not_found` | No such deal, or the credential's owner can't see it |
| `409 commissions_off` | The workspace turned commissions off |

> [card] [MCP tools](https://docs.useorbitcrm.ai/mcp/tools.md)
>
> The same operations as MCP tools

> [card] [App permissions](https://docs.useorbitcrm.ai/apps/permissions.md)
>
> Every scope and what it allows

> [card] [Reports API](https://docs.useorbitcrm.ai/developers/api/reports.md)
>
> Goals, forecasts and sales reports


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.