Scopes
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 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 exceptsettingsanswers409 commissions_off, until someone with Manage commissions sendsenabled: 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_splitsetting 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:Endpoints
All paths start withhttps://app.useorbitcrm.ai/api/v1/commissions. Ids are UUIDs and dates are YYYY-MM-DD.
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
GET /settings answers { data: { settings, access } }:
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.
Plans
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.
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).
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)
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:
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:
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
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:
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.
It answers
{ period: { start, end }, earnings }: earnings has the quotas, the lines (see 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.
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:
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):approvelocks each statement as it calculates now. Only a period that is over can be approved.payrecords each as paid now, withnoteas the payment reference (up to 500 characters). Withapprovalson, a statement must be approved first; with them off,payalso locks it.reopenunlocks 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.
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.
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 ascorrection_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:GET /adjustments?period_start=lists a period’s adjustments for the people the credential’s owner can see;period_startis required, andplan_idanduser_idnarrow it.POST /adjustmentstakes{ user_id, plan_id?, period_start, amount, note }and answers201.amountis not zero, up to 1,000,000,000 either way, to the cent;noteis 1 to 500 characters. Withoutplan_idit lands on the person’s first plan with a period starting that day. The person must be on the plan in that period, andperiod_startmust start one of its periods (422 invalid_requestotherwise).DELETE /adjustments/:idanswers{ "deleted": true }.
409 statement_locked (reopen it first). kind is correction for one made by POST /corrections.
Objective scores
For plans with anmbo component, PUT /mbo-scores sets a person’s objective scores for a period, in %:
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).
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.
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 workspacedefault_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):
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:
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:
{ "kind": "rate", "value": 5 }: 5% of the deal’s amount.
MCP tools
The same operations as MCP tools
App permissions
Every scope and what it allows
Reports API
Goals, forecasts and sales reports