Copy page

Business models

Outcome-Based Professional Services

The outcome-based services pricing pattern: instead of billing for hours worked or seats provisioned, you bill when defined milestones are delivered - a project phase signed off, a healthcare encounter completed, an SLA target met, a regulatory filing accepted. The economics align supplier and client around results instead of effort. The hard parts are defining the milestones unambiguously, capturing the evidence that triggers each charge, and getting both sides to agree the milestone has actually been hit.

Real-world examples. Consulting firms (McKinsey/BCG/Bain billing on project phases), creative agencies (per-deliverable invoicing), legal practices (matter-based billing), healthcare providers (per-encounter or per-procedure billing), construction (progress-payment milestones), software-as-a-service-with-success-fee variants (charge X% of customer's revenue gain), regulated services (charge per accepted regulatory filing). Common shape: contract defines a list of milestones with associated fees, each milestone has acceptance criteria, charge fires when the criteria are met, both parties sign off on the milestone, audit trail tracks the evidence end-to-end.

The shape of the problem

Outcome-based billing replaces "regular calendar invoice" with "event-driven invoice," which surfaces unique constraints:

• Milestone definition is the contract. What exactly counts as "phase 1 delivered"? Acceptance criteria need to be unambiguous, machine-checkable where possible, and tied to evidence both sides can verify.
• Asymmetric trigger sources. Some milestones trigger automatically (SLA target met, regulatory acceptance received via API), some require manual approval (client signs off on a deliverable), some need both (system says it's done, client confirms before charge fires).
• Evidence trail. When the customer disputes the charge three months later, you need to show the sign-off, the supporting documents, and the timestamp. Compliance auditors expect the same.
• Partial milestones. Phase 1 delivered at 90% completion - charge 90% now, 10% on full delivery? Many contracts allow tiered acceptance.
• Milestone sequencing and dependencies. Phase 2 can't bill until Phase 1 is accepted. Phase 3 fires only if Phase 2 hits a specific KPI.
• Hold-back / retention. Common in construction: 10% of every milestone held back until the entire project is signed off, released as a final settlement.

Kontorion blueprint

Concern	Kontorion primitive
Milestone definition with fee	One-shot invoice line per project phase
Evidence trail	Milestone metadata

Build it

1. Set up the customer and project

Code
curl -X POST https://api.kontorion.eu/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "external_id": "client_globex_ent",
    "name": "Globex Enterprises",
    "email": "ap@globex.example",
    "preferred_currency": "USD",
    "payment_terms_days": 30
  }'

curl -X POST https://api.kontorion.eu/v1/subscriptions \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "customer_id": "cust_globex",
    "plan_id": "plan_consulting_engagement",
    "items": [{ "price_id": "price_consulting_engagement" }],
    "metadata": {
      "engagement_id": "eng_2025_globex_transformation",
      "engagement_type": "outcome_based",
      "lead_partner": "user_alice"
    }
  }'

2. Define the milestones for the engagement

A typical 3-phase consulting project:

Code
# Phase 1: Discovery & Assessment - 20% on signed assessment report
curl -X POST https://api.kontorion.eu/v1/subscriptions/sub_globex_eng/milestones \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "product_id": "prod_consulting_milestone",
    "name": "Phase 1: Discovery & Assessment",
    "percentage": 0.20,
    "trigger_type": "MANUAL",
    "description": "Phase 1: Discovery & Assessment - signed assessment report",
    "metadata": {
      "phase": "1",
      "acceptance_criteria": "Signed assessment report delivered and acknowledged by Globex CIO",
      "deliverables": "assessment_report.pdf,stakeholder_map.xlsx"
    }
  }'

# Phase 2: Implementation Plan - 30% on approved plan
curl -X POST https://api.kontorion.eu/v1/subscriptions/sub_globex_eng/milestones \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "product_id": "prod_consulting_milestone",
    "name": "Phase 2: Implementation Plan",
    "percentage": 0.30,
    "trigger_type": "MANUAL",
    "description": "Phase 2: Implementation Plan - approved by steering committee",
    "metadata": {
      "phase": "2",
      "depends_on_milestone": "ms_phase_1_globex"
    }
  }'

# Phase 3: Delivery & Handover - 40% base
curl -X POST https://api.kontorion.eu/v1/subscriptions/sub_globex_eng/milestones \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "product_id": "prod_consulting_milestone",
    "name": "Phase 3 base: Delivery complete",
    "percentage": 0.40,
    "trigger_type": "MANUAL",
    "description": "Phase 3: Delivery complete",
    "metadata": {
      "phase": "3",
      "depends_on_milestone": "ms_phase_2_globex"
    }
  }'

# Phase 3 bonus: 10% on KPI achievement
curl -X POST https://api.kontorion.eu/v1/subscriptions/sub_globex_eng/milestones \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "product_id": "prod_consulting_milestone",
    "name": "Phase 3 bonus: 30% efficiency improvement KPI",
    "percentage": 0.10,
    "trigger_type": "MANUAL",
    "description": "Phase 3 bonus: 30% efficiency improvement validated",
    "metadata": {
      "phase": "3-bonus",
      "depends_on_milestone": "ms_phase_3_base_globex"
    }
  }'

percentage is a JSON number representing a fraction of the resolved product price - it must be greater than 0 and at most 1 (so 20% is 0.20, not 20). At trigger time the milestone bills resolved_price × percentage. Each milestone references a product_id that must exist in the subscription's plan-version snapshot.

3. Configure approval workflow for milestone acceptance

When the feature ships, you will register a reusable workflow template and route milestone triggers through it. The current template shape is:

Code
# Planned — routes disabled today.
curl -X POST https://api.kontorion.eu/v1/approval-workflows \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "name": "Outcome-services milestone acceptance",
    "entity_type": "SUBSCRIPTION",
    "trigger_action": "ACTIVATE",
    "on_timeout": "ESCALATE",
    "on_rejection": "HOLD",
    "steps": [
      {
        "step_number": 1,
        "name": "Internal lead partner sign-off",
        "approver_roles": ["delivery_lead"],
        "min_approvals": 1,
        "timeout_hours": 48,
        "notify_on_start": true
      },
      {
        "step_number": 2,
        "name": "Client AP sign-off",
        "approver_roles": ["client_ap"],
        "min_approvals": 1,
        "timeout_hours": 168,
        "notify_on_start": true
      }
    ]
  }'

Note that the real CreateWorkflowTemplateRequest accepts name, entity_type, trigger_action, steps, and optional description, on_timeout, and on_rejection. Each step uses step_number, name, approver_roles / approver_user_ids, min_approvals, timeout_hours, and notify_on_start. There is no trigger_conditions field, and entity_type must be one of the supported entities (for example SUBSCRIPTION, INVOICE, PRODUCT) — there is no BILLING_MILESTONE entity type today.

4. Trigger Phase 1 sign-off

When the consulting team finishes the assessment and the client signs off, trigger the milestone. The trigger endpoint takes the subscription and milestone IDs in the path and no request body - the milestone must be in PENDING status and its subscription must be ACTIVE:

Code
curl -X POST https://api.kontorion.eu/v1/subscriptions/sub_globex_eng/milestones/ms_phase_1_globex/trigger \
  -H "Authorization: Bearer sk_live_..."

Triggering is synchronous and not gated by any approval workflow today: the milestone resolves the product's price, applies its percentage, calculates tax, and immediately creates a draft invoice with a milestone line. The milestone moves to TRIGGERED and the response carries the milestone plus the new invoice_id:

Code
{
  "milestone": {
    "id": "ms_phase_1_globex",
    "subscription_id": "sub_globex_eng",
    "product_id": "prod_consulting_milestone",
    "name": "Phase 1: Discovery & Assessment",
    "percentage": "0.2",
    "status": "TRIGGERED",
    "trigger_type": "MANUAL",
    "triggered_at": "2025-04-15T14:30:00Z",
    "invoice_id": "inv_globex_apr_phase1"
  },
  "invoice_id": "inv_globex_apr_phase1"
}

Capture sign-off evidence (signed PDF URL, approver, timestamp) in the milestone's metadata at creation time - the trigger call itself does not accept or store any body.

5. Inspect the milestone

Read a single milestone to see its current status, when it was triggered, the invoice it generated, and the evidence you stored in metadata:

Code
curl https://api.kontorion.eu/v1/subscriptions/sub_globex_eng/milestones/ms_phase_1_globex \
  -H "Authorization: Bearer sk_live_..."

Code
{
  "id": "ms_phase_1_globex",
  "subscription_id": "sub_globex_eng",
  "product_id": "prod_consulting_milestone",
  "name": "Phase 1: Discovery & Assessment",
  "percentage": "0.2",
  "status": "TRIGGERED",
  "trigger_type": "MANUAL",
  "triggered_at": "2025-04-15T14:30:00Z",
  "invoice_id": "inv_globex_apr_phase1",
  "metadata": {
    "acceptance_criteria": "Signed assessment report delivered and acknowledged by Globex CIO",
    "evidence_url": "https://docs.acme.example/globex/phase1_assessment_signed.pdf",
    "signoff_user_id": "user_globex_cio"
  },
  "is_overdue": false
}

List every milestone on the engagement with GET /v1/subscriptions/sub_globex_eng/milestones. For org-wide change history (who created or triggered what, and when), query the platform audit events feed - there is no dedicated /audit sub-resource on milestones.

6. Apply 10% retention across the engagement

For projects with retention/holdback (common in regulated industries and construction-style engagements), the planned model would withhold a percentage of each milestone payment and release it on final sign-off:

Code
# Planned — endpoint does not exist today.
curl -X POST https://api.kontorion.eu/v1/counterparties \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "name": "Globex retention escrow",
    "type": "internal_escrow",
    "currency": "USD",
    "linked_subscription_id": "sub_globex_eng",
    "withholding_rules": [
      { "type": "retention", "rate": 0.10, "release_condition": "engagement_final_signoff" }
    ]
  }'

Until this ships, model retention manually - for example, set each milestone percentage to the net (post-retention) fraction and trigger a separate final milestone for the held-back remainder once the engagement is signed off.

Variations

• Time-and-materials hybrid. Combine outcome-based milestones with usage events for billable hours. Some deliverables fire milestone charges, while underlying T&M still bills monthly per timesheet.
• Healthcare per-encounter billing. Each encounter is a one-shot milestone with the procedure code in metadata; payer rules (configured per customer.metadata.payer_id) determine reimbursement amount and timing.
• SLA-conditional charges. Milestone fires only when the SLA dashboard reports target hit (e.g., "99.9% uptime achieved this month"). Use a webhook from your monitoring system as the trigger source.
• Success-fee model. Charge X% of measured customer revenue gain. Milestone evaluates a customer-reported metric (or pulls from an integrated analytics system) and creates a percentage-based invoice line.
• Regulatory acceptance billing. Charge fires when a regulator's API confirms a filing is accepted (e.g., FDA submission accepted, HMRC return processed). Webhook from your filing system carries the regulator's confirmation ID.
• Bonus + clawback. Bonus milestone fires on KPI hit; if KPI deteriorates within N months, an automatic credit note claws back a portion. Implement via paired milestones and time-bounded conditions.

What you don't have to build

• Milestone trigger orchestration (POST /v1/subscriptions/{subscriptionId}/milestones/{id}/trigger plus an HMAC-signed webhook variant at POST /v1/webhooks/billing-milestones/{id})
• Synchronous price resolution, tax calculation, and draft-invoice line generation on trigger
• Per-engagement custom acceptance criteria and evidence references (live in milestone metadata)
• KPI-based bonus calculations (external event payloads carry the metrics)

Planned but not yet available (do not build against these today):

• Multi-party sign-off workflows with timeouts and escalation (approval-workflows routes are disabled, and not wired to milestone triggers)
• Enforced dependency graphs between milestones — depends_on_milestone is free-form metadata you record yourself; the API does not block out-of-order triggers
• Retention escrow accounting and timed release

Next steps

• Billing Milestones - the milestone primitive used throughout this guide
• Approval Workflows - dual sign-off and gating (roadmap; routes currently disabled and not wired to milestone triggers)
• Subscriptions - the engagement container
• Custom Fields - storing acceptance criteria and evidence references