> ## 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.

# Policy lifecycle

> Crop and livestock cover, from quote to determination to cancellation.

## Products

| Product          | `productType` | Keyed to                         | Sum insured              |
| ---------------- | ------------- | -------------------------------- | ------------------------ |
| Crop (index)     | `CROP`        | a **plot** (`plotId`)            | you specify `sumInsured` |
| Livestock (IBLI) | `LIVESTOCK`   | a **herd** (`herdId`) + `season` | auto-calculated from TLU |

Coverage types: crop — `DROUGHT`, `FLOOD`, `BOTH`, `COMPREHENSIVE`; livestock —
`LIVESTOCK_DROUGHT`, `LIVESTOCK_DISEASE`, `LIVESTOCK_COMPREHENSIVE`. Livestock seasons:
`LRLD`, `SRSD`. Livestock cover is available only in markets where it is enabled — read
`checklist.livestockEnabled` from `GET /api/organizations/me/kyb`.

## States

```mermaid theme={null}
flowchart LR
  Q[quote] --> P[PENDING]
  P -->|premium paid or attested| A[ACTIVE]
  A -->|index evaluated| D[determination issued]
  A -->|term ends| EX[EXPIRED]
  P -->|cancel| C[CANCELLED]
  A -->|cancel| C
```

| Status      | Meaning                                                 |
| ----------- | ------------------------------------------------------- |
| `PENDING`   | Created, awaiting premium.                              |
| `ACTIVE`    | Premium paid (Tier 2) or attested (Tier 1); cover live. |
| `EXPIRED`   | Past its end date.                                      |
| `CANCELLED` | Cancelled (pro-rata refund if it was paid).             |

## 1. Quote

`POST /api/policies/quote` returns the premium, platform fee and a breakdown. It writes
nothing and is **not** gated, so you can quote before going live. See the
[Quickstart](/quickstart#3-quote-a-policy) for crop; for livestock:

```bash theme={null}
curl -X POST https://app.microcrop.app/api/policies/quote \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{ "farmerId": "f1…", "productType": "LIVESTOCK", "herdId": "h1…", "season": "LRLD" }'
```

## 2. Purchase

`POST /api/policies/purchase` (same body as quote) creates a `PENDING` policy and
**freezes `settlementMode`** onto it.

| Condition                                               | Error                                                              |
| ------------------------------------------------------- | ------------------------------------------------------------------ |
| Not KYB-verified                                        | `403 FORBIDDEN`                                                    |
| Regulator licence missing / expired                     | `403 REGULATOR_LICENSE_REQUIRED` / `403 REGULATOR_LICENSE_EXPIRED` |
| Farmer KYC not approved                                 | `400 INVALID_INPUT`                                                |
| Duplicate active policy on the plot/herd                | `400 INVALID_INPUT`                                                |
| No live solvency attestation, or over attested capacity | `400 INVALID_INPUT`, naming the condition and the binding limit    |
| Attestation currency ≠ policy currency                  | `400 INVALID_INPUT` — capacity is never converted                  |

Both service tiers may **sell**. The tier decides who settles, not whether cover exists.

## 3. Premium & activation

<Tabs>
  <Tab title="Tier 1 — DETERMINATION">
    You collect premium off-platform, then attest it:

    ```bash theme={null}
    curl -X PUT https://app.microcrop.app/api/policies/po1…/activate \
      -H "x-api-key: $KEY" -H "Content-Type: application/json" \
      -d '{ "paymentReference": "SFH7TQ2K91", "reason": "Premium collected on the Acme till, reconciled 2026-09-01" }'
    ```

    `POST /api/payments/initiate` returns `403 TIER_NOT_ENTITLED` on these policies.
  </Tab>

  <Tab title="Tier 2 — DETERMINATION_AND_SETTLEMENT">
    Collect the premium with M-Pesa (`POST /api/payments/initiate`). On a successful
    payment MicroCrop creates the policy on-chain and flips it to `ACTIVE`
    automatically. See [Payments](/guides/payments).

    `PUT /api/policies/{policyId}/activate` also works here, as a reconciliation
    fallback for premium that arrived off-platform.
  </Tab>
</Tabs>

`PUT /api/policies/{policyId}/activate` requires the `policy:activate` capability, both
`paymentReference` and `reason`, and a policy in `PENDING` with no provider payment
outstanding. It records an audited `manual: true`, `providerVerified: false` premium
transaction.

## 4. Determination

Cover is **parametric** — there are no claims to file. An off-chain oracle computes the
index; MicroCrop issues a signed determination stating whether the trigger fired and the
measured damage in basis points. This happens on **both** tiers.

```bash theme={null}
curl "https://app.microcrop.app/api/determinations?policyId=po1…" -H "x-api-key: $KEY"
```

See [Determinations](/guides/determinations) for the response shape, and
[Verification](/guides/verification) to check it without trusting us.

## 5. Settlement

<Tabs>
  <Tab title="Tier 1 — DETERMINATION">
    **You** pay the farmer, off-platform, off your own balance sheet, in the policy's own
    currency. The determination tells you the amount owed
    (`settlement.amountOwed.amountMinor`). Then report it back with
    `POST /api/determinations/{id}/settlement-report`.

    `GET /api/policies/{id}/status` returns an empty `payouts[]` on these policies — by
    design, not by omission. See [Tier 1 integration](/guides/tier-1-integration).
  </Tab>

  <Tab title="Tier 2 — DETERMINATION_AND_SETTLEMENT">
    MicroCrop originates and settles the payout to the farmer. You observe it:

    ```bash theme={null}
    curl "https://app.microcrop.app/api/payouts?status=PROCESSING" -H "x-api-key: $KEY"
    ```

    Payout statuses progress `PENDING → PROCESSING → COMPLETED` (or `FAILED`, which you
    can retry with `POST /api/payouts/{payoutId}/retry`). Retrying a payout on a Tier 1
    policy is `403 TIER_NOT_ENTITLED`.
  </Tab>
</Tabs>

## 6. Cancellation

```bash theme={null}
curl -X POST https://app.microcrop.app/api/policies/po1…/cancel \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{ "reason": "Farmer requested cancellation" }'
```

Only `PENDING` or `ACTIVE` policies can be cancelled. A paid, active policy gets a
**pro-rata refund** for the unused term.

<Card title="Track changes" icon="arrows-rotate" href="/guides/status-tracking">
  How to poll efficiently for lifecycle, determination and payout updates.
</Card>