Renewals Engine

Internal only

This document contains protected Ikamet operational intelligence. Access restricted to Ikamet team via Cloudflare Access.

Purpose

The renewals engine ensures that no permit or policy expires without proactive action. It runs on a daily schedule and maintains the days_until_due field on every Renewal record.

How it works

Every Renewal record stores:

• service_type — what is being renewed (residence permit, insurance policy, etc.)
• due_date — the expiry date
• days_until_due — calculated daily by the engine
• status — current state of the renewal

Daily refresh

The runRenewalsRefresh() function runs nightly (scheduled via cron):

1. Calculates days_until_due for every active renewal
2. Flags records as OVERDUE where days_until_due < 0
3. At threshold crossings, writes a RENEWAL_TRIGGERED timeline event
4. The timeline event triggers downstream notifications (WhatsApp, email, task creation)

Alert thresholds

Days until due	Action
90	First alert — early planning
60	Outreach sequence begins
30	Urgent reminder
14	High-priority task created for assigned agent
7	Escalation — URGENT priority task
< 0	Status → OVERDUE; compliance flag

API endpoint

The renewals cron is triggered via:

POST /ops/renewals/refresh

This endpoint is called by the scheduled job and can also be triggered manually from ops.ikamet.com.

Creating a renewal

Renewals are created automatically when:

• A policy is issued (linked to the policy’s end_date)
• A residence permit is approved (linked to the permit expiry)
• A work permit is issued

They can also be created manually:

POST /ops/customers/:id/renewals
{
  "service_type": "RESIDENCE_PERMIT",
  "due_date": "2026-03-15",
  "policy_id": "pol_abc123",
  "notes": "Standard 1-year permit"
}

Completing a renewal

When a renewal is processed (new permit issued, policy renewed):

PATCH /ops/renewals/:renewal_id/complete

This:

1. Marks the renewal as COMPLETED
2. Writes a RENEWAL_COMPLETED timeline event
3. Creates a new Renewal record for the next expiry (if applicable)

Global renewals queue

The /renewals page in ops.ikamet.com shows all upcoming renewals across all customers, filterable by:

• Days window (30 / 60 / 90 / 180 days)
• Service type
• Status

Sorted by urgency — overdue renewals appear first.