OutputValues icon
If icon
Fail icon
Queries icon
Log icon
UploadFiles icon
Switch icon
Set icon
SlackIncomingWebhook icon

Calculate customer SLA service credits from incidents and issue the credit notes

Monthly SLA credit run in Kestra and DuckDB. Merged downtime, maintenance and customer exclusions, tiered credits, caps, claims and credit notes.

Categories
BusinessInfrastructure

Every SaaS or hosting contract has an uptime commitment and a credit schedule, and most companies apply it by hand when a customer complains. That breaks in both directions:

  • over-crediting: overlapping incidents are counted twice, or announced maintenance is counted as downtime;
  • under-crediting: enterprise customers whose credits are automatic never receive them. That is a breach of contract that surfaces at renewal.

This flow computes every customer's uptime on the services and regions they actually use, applies their contract, and issues the credit notes.

It runs with no setup and no network. The demo has three services in three regions and 80 customers on enterprise, business and standard tiers. The month's incidents are:

  • two overlapping API incidents in us-east (a failover, then a cache stampede during recovery);
  • a dashboard outage that one customer caused itself;
  • a maintenance announced nine days ahead, and another announced only five hours ahead;
  • a long data-export outage, and a seven-minute certificate expiry.

Rules

Step Rule
Countable downtime Incidents clipped to the month. Scheduled maintenance is excluded only if announced at least maintenance_notice_hours ahead
Overlaps Merged per service and region (gaps-and-islands), so a minute is never counted twice
Customer-caused Excluded for the customer that caused it only
Uptime Per customer and service, on the customer's own region
Credit The tier's schedule (for example, enterprise: 10% of the service fee below 99.95%, 25% below 99.9%, 50% below 99%), summed over services
Cap The contract cap, as a share of the monthly fee
Claim Enterprise credits are automatic. Business and standard credits are issued only if claimed within the claim window. The rest is reported as awaiting a claim

Credit notes are produced for automatic and claimed credits, with a revenue-reduction journal per currency.

How it works

  1. state and period_gate refuse a month already issued.
  2. credits (io.kestra.plugin.jdbc.duckdb.Queries):
    • holds the services, tiers, contracts, subscriptions, incidents and claims;
    • checks the data, then computes countable and merged downtime, downtime per customer, credits and caps, claim status, credit notes and the journal.
  3. log_run prints the result. evidence stores customers.csv (uptime by service, credit before and after the cap, status), downtime.csv (merged windows and the incidents in each), credit-notes.csv, journal.csv and blockers.csv.
  4. decide (io.kestra.plugin.core.flow.Switch):
    • ISSUE locks the month.
    • Otherwise the run fails: NEEDS_APPROVAL (credits above 25,000 or a customer at the cap) or BLOCKED.
  5. The errors block posts to Slack when any step fails and notify_slack is true, including a blocked month or a missing approval.

Tested end to end

On Kestra 2.0.3 OSS.

Run Inputs Result
1 2026-09 The two overlapping us-east incidents merge into 180 minutes (1,482 minutes before merging, 1,442 after). The maintenance with nine days' notice is excluded; the one with five hours' notice is counted. The customer-caused dashboard outage is excluded for CUS-017 only. 42 customers owed credit: 16 automatic, 7 claimed, 19 awaiting a claim (2,531.61). 9 enterprise customers hit the 15% cap. Stops for approval
2 same, approved_by 16,154.85 issued as credit notes, month locked
3 again Refused
4 2026-10 ISSUES Blocked: an incident still open, an incident ending before it starts, a subscription to an unknown service

I recomputed the credit of all 80 customers independently in Python, from the incident minutes, the tier schedules, the fee weights and the cap. None differs.

Inputs

Input Default Purpose
month 2026-09 YYYY-MM, validated
scenario CLEAN Demo only
maintenance_notice_hours 72 Notice needed for maintenance to be excluded
approved_by empty Needed above 25,000 or at the cap

Secrets

  • SLACK_WEBHOOK_URL: used by errors when notify_slack is true.

Use it with your data

  • Replace incidents with your incident tool or status page history (service, region, start, end, kind, announcement time), and customer_caused with the incidents' root cause attributions.
  • Replace tiers, contracts, subscriptions and claims with your SLA terms, billing and support tickets.
  • Post credit-notes.csv to billing, so the credit applies to the next invoice.

Things to know

  • Uptime is measured on minutes of full outage. Partial degradation (error rate, latency) needs its own measure, for example from synthetic checks.
  • Some contracts measure per region across all services, or across all regions. Change the grouping in customer_downtime.

Links

This blueprint was created by zkasuran.

See How

New to Kestra?

Use blueprints to kickstart your first workflows.