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

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 for crop; for livestock:

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

Tier 1 — DETERMINATION

You collect premium off-platform, then attest it:

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.

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.

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

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.

curl "https://app.microcrop.app/api/determinations?policyId=po1…" -H "x-api-key: $KEY"

See Determinations for the response shape, and Verification to check it without trusting us.

5. Settlement

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.

Tier 2 — DETERMINATION_AND_SETTLEMENT

MicroCrop originates and settles the payout to the farmer. You observe it:

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.

6. Cancellation

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.

Track changes

How to poll efficiently for lifecycle, determination and payout updates.