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

# Service tiers

> What DETERMINATION buys, what DETERMINATION_AND_SETTLEMENT adds, and exactly where our responsibility ends.

MicroCrop sells two things. Only one of them is money.

|                                                                | `DETERMINATION` (Tier 1) | `DETERMINATION_AND_SETTLEMENT` (Tier 2) |
| -------------------------------------------------------------- | ------------------------ | --------------------------------------- |
| We compute the index and decide whether the trigger fired      | Yes                      | Yes                                     |
| We issue a signed, independently verifiable determination      | Yes                      | Yes                                     |
| We issue the evidence package a third party can re-verify      | Yes                      | Yes                                     |
| We tell you the amount owed, in **your policy's own currency** | Yes                      | Yes                                     |
| We collect the farmer's premium                                | No — you do              | Yes, via M-Pesa                         |
| We pay the farmer                                              | **No — you do**          | Yes                                     |
| We hold your capital                                           | **No**                   | **No**                                  |
| We verify that you paid the farmer                             | **No**                   | n/a                                     |

New organizations start on `DETERMINATION`.

## The product on Tier 1 is the determination

A parametric policy has exactly one hard question: *did the trigger fire, and by how
much?* Everything else — collecting premium, moving money, reconciling with a farmer — is
work you almost certainly already do, on rails you already own, under a licence you
already hold.

Tier 1 sells you the answer to the hard question, in a form your regulator, your
reinsurer and your auditor can check **without asking us anything**:

* a **chain-neutral, currency-neutral canonical body** — the facts of the determination,
  with every numeric value encoded as a decimal string so no float ever enters the record;
* its **SHA-256 hash**, reproducible byte-for-byte in any language;
* an **off-chain signature** over that hash, from which anyone can recover our signer;
* a **notary anchor** so the hash is provably older than any dispute about it;
* the **source provenance** — the inputs, and where they came from — so a sceptic can
  re-fetch the data and recompute the index themselves.

That artifact is what you buy. [Verify it yourself](/guides/verification) — the whole
design assumes you will, and it works with our servers switched off.

## What Tier 2 adds

Tier 2 adds money movement: MicroCrop collects the farmer's premium by M-Pesa, activates
the policy on-chain, and originates and settles the payout to the farmer when a
determination triggers. Everything from Tier 1 still applies — the determination and its
evidence package are identical, and identically verifiable.

Tier 2 does **not** mean MicroCrop underwrites the risk or funds the payout. Capital is
yours in both tiers.

## Where our responsibility ends

We state this plainly because vagueness here is how parametric programmes go wrong.

**On Tier 1, MicroCrop:**

* determines whether the parametric trigger fired, per the methodology version frozen onto
  the policy at purchase;
* states the amount owed, derived from *the policy you sold* — `sumInsured ×
  damagePercentBp / 10000`, truncated to the minor unit, in the policy's own currency;
* issues the signed determination and evidence package, and notifies you.

**On Tier 1, MicroCrop does not:**

* collect, hold, route or disburse any money — not the premium, not the payout;
* hold or custody your capital, on any tier;
* decide whether you owe the farmer as a matter of contract or of law. We determine what
  the index says. What your policy wording, your regulator and your customer contract make
  of that is yours;
* **verify that you paid the farmer.** When you tell us what you paid, we store it and
  echo it back labelled `verifiedByMicrocrop: false`, always. The field that would record
  a MicroCrop verification is a one-valued enum — `UNVERIFIED` — so no code path can even
  express the opposite;
* chase, dun or enforce anything. If you never report a settlement, the determination is
  marked `OVERDUE`. That is a **reporting** state. MicroCrop did not settle the policy,
  owes nothing on it, and has moved no money.

<Note>
  This page describes the engineering behaviour of the system, not your legal position.
  **\[PLACEHOLDER — FOR COUNSEL]** The contractual allocation of liability between MicroCrop
  and the partner, and the regulatory characterisation of a determination in each market,
  belong in the partner agreement and are not settled by this documentation.
</Note>

## Three facts, never collapsed into one status

This is the shape of every determination response, and it is deliberate. A single status
field would have to lie about at least one of these:

<CardGroup cols={3}>
  <Card title="determined" icon="signature">
    What **we** determined. Signed, hashed, anchored, independently verifiable.
  </Card>

  <Card title="settlement" icon="ban">
    Whether **we** settled. On Tier 1 it says explicitly that we deliberately did **not**,
    and what the policy owes.
  </Card>

  <Card title="partnerReport" icon="file-pen">
    What **you** told us happened. Always labelled partner-attested and **not** verified
    by MicroCrop. Never merged into `settlement`.
  </Card>
</CardGroup>

A merged status that read `UNPAID` would look like a broken determination. One that read
`PAID` would launder your unverified claim into a MicroCrop fact. Neither is acceptable,
so we never produce one. See [Determinations](/guides/determinations).

## How the tier is applied

Two fields, and the distinction between them is the whole safety property:

| Field                      | Where                                                         | Mutable?                                 | Meaning                                                                  |
| -------------------------- | ------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
| `Organization.serviceTier` | `GET /api/organizations/me` → `data.serviceTier`              | Yes — a MicroCrop-side commercial change | What your organization bought. Governs **future sales only**.            |
| `Policy.settlementMode`    | on every policy, and on `determination.policy.settlementMode` | **No — frozen at purchase**              | Who owes **this** farmer for **this** cover, for the life of the policy. |

At `POST /api/policies/purchase`, your organization's current tier is projected onto the
new policy and frozen there — the same mechanism that freezes `methodologyVersion`, for
the same reason.

**The tier gates intake; it never drains.** Every enforcement point in the system reads
`Policy.settlementMode`, never your organization's current tier. So:

* a **downgrade** from Tier 2 to Tier 1 cannot strand an in-flight payout on cover you
  sold under Tier 2 — those policies keep settling;
* an **upgrade** from Tier 1 to Tier 2 does not retroactively make MicroCrop liable for
  cover it never priced — those policies stay yours to settle.

The check is written in the deny direction (`settlementMode !== DETERMINATION_AND_SETTLEMENT`
refuses), so a missing, unknown or future value refuses rather than slipping through.

## What each tier gates, concretely

| Endpoint                                                   | Tier 1 policy             | Tier 2 policy               |
| ---------------------------------------------------------- | ------------------------- | --------------------------- |
| `POST /api/policies/quote`                                 | ✅                         | ✅                           |
| `POST /api/policies/purchase`                              | ✅                         | ✅                           |
| `PUT /api/policies/{id}/activate`                          | ✅ (the normal path)       | ✅ (reconciliation fallback) |
| `POST /api/payments/initiate`                              | ❌ `403 TIER_NOT_ENTITLED` | ✅                           |
| `GET /api/determinations` and `/{id}` and `/{id}/evidence` | ✅                         | ✅                           |
| `POST /api/determinations/{id}/settlement-report`          | ✅                         | ❌ `403 NOT_PARTNER_SETTLED` |
| `GET /api/payouts`                                         | ✅ (always empty)          | ✅                           |
| `POST /api/payouts/{id}/retry`                             | ❌ `403 TIER_NOT_ENTITLED` | ✅                           |

Determination **reads are never tier-gated**. Both tiers determine; gating the reads on
the settlement tier would hide the Tier 1 product from the people who bought it.

<Warning>
  `403 TIER_NOT_ENTITLED` is a permanent commercial refusal, not a transient failure. Do
  not retry it, and do not queue behind it. It means the policy was sold under
  `DETERMINATION` and MicroCrop will never settle it.
</Warning>

## Changing tier

There is no partner endpoint. Contact MicroCrop; a change requires a written reason and is
recorded in an append-only audit trail with how much cover was in force under the old
mode. It takes effect on the **next** sale.

<CardGroup cols={2}>
  <Card title="Tier 1 integration" icon="route" href="/guides/tier-1-integration">
    The full path: sell, activate, determine, settle, report.
  </Card>

  <Card title="Independent verification" icon="shield-check" href="/guides/verification">
    Check our determination without trusting or calling us.
  </Card>
</CardGroup>