Finance — Subsidy

Subsidy affects eligibility, billing/payment, and reporting. This wiki places Subsidy under Finance because OpenSpec currently has only a few subsidy capabilities, while this business mostly affects financial obligations.

Concepts

Concept	Meaning
SubsidyAcceptance	Record of subsidy approval per attendee/date range; usually used to determine eligibility.
Subsidy policy	Rules applying subsidy by site/BU/programme/country.
Site licence setup	Licence/eligibility configuration at the site that makes subsidy effective.
Allocation	How subsidy is attached to billing/invoice/payment to reduce the customer's obligation.

Interactions with other domains

Domain	Interaction
Booking	May check subsidy when determining deposit eligibility or pricing context.
Payment	Deposit eligibility uses SubsidyAcceptance per attendee, not a general subsidy state on the account.
Billing/Invoice	Subsidy can affect amount, allocation, and financial reporting.
Master Data	Site/BU/attendee are the main scope to determine a valid subsidy.

Rules to remember

• Eligibility should be based on a specific attendee and date range.
• If subsidy is only a site/BU config, do not treat it as collected payment.
• When subsidy changes, re-check the impact on invoice/payment/reporting instead of only fixing the UI display.

Subsidy programmes

Subsidy is government welfare funding that reduces childcare costs for eligible families — not a discount, credit note, or internal budget mechanism. Enabled per BusinessUnit via BusinessUnit.SubsidyTypeId.

SubsidyType	Value	Jurisdiction	Programme
NZ_OSCAR	1	New Zealand	OSCAR (Out of School Care and Recreation)
IRELAND_NCS	2	Ireland	NCS (National Childcare Scheme)
CANADA_ALBERTA	3	Canada	Alberta Child Care Subsidy

Two allocation paths

Path	Programme	Flow
Batch allocation	OSCAR / Alberta	Upload gov file (PDF/CSV) → SubsidyBatch + SubsidyBatchLine → fuzzy match attendee/contact → staff review → ApproveAllocationAsync → SubsidyBatchLineAllocation → Payment → Xero sync
Estimation allocation	Ireland NCS	SubsidyAcceptance approved → attendance records → round hours → × rate → SubsidyEstimation + SubsidyEstimationAllocation → Invoice → Payment + Xero sync

• Batch: line amount allocates into the invoice account FIFO by due date; over-allocation is stored as overpayment, not rejected (INV-SUB-13).
• Estimation: rounds hours before multiplying by the rate; rounding rule None/15min/30min/Hour (ceil, not floor) (INV-SUB-05).

Real-world example: An NZ site uploads the July OSCAR file → the system matches each child line to Attendee/Contact (OCR drift → staff fix manually) → Approve → allocation reduces the invoice AmountDue by FIFO; the remainder becomes overpayment.

Real-world example: An Ireland NCS BU has an approved acceptance (StatusId=500), attendance 90 minutes, rule 15min, rate €X → round 90→90 minutes then × rate, creates an estimation → approve then allocates into the invoice.

Core entities

Entity	Role
SubsidyBatch / SubsidyBatchLine	Uploaded gov batch + per-child lines.
SubsidyBatchLineAllocation	Allocation lines into invoice payment.
SubsidyAcceptance	Subsidy approval for 1 child; the status machine defines the lifecycle.
SubsidyRate / SubsidyRateLine	Rate master + lines effective by date range.
SubsidyEstimation / SubsidyEstimationBatch / SubsidyEstimationAllocation	Ireland NCS: per-child/period estimation + container + allocation.
SubsidyReducedEnrolment	NZ compliance: tracks under-attendance.
OcrSubsidyBatch	OCR metadata from PDF upload; low-confidence lines need staff correction (INV-SUB-11).

SubsidyAcceptance status machine

100 (Draft)     ← tạo tại Booking Confirm
  ↓
300 (Pending)   ← staff submit review
  ↓
500 (Approved)  ← staff approve; dùng cho estimation
  ↓ (hoặc từ bất kỳ state nào)
600 (Archived)

• Important: SubsidyAcceptance is created at Booking Confirm, not Submit (INV-SUB-08); Contact.SocialBenefitNumber can be updated at confirm (INV-SUB-12).
• Only StatusId = 500 may be used in estimation (INV-SUB-03); the valid transition is 100 → 300 → 500 (INV-SUB-02).
• Eligibility: ProgramCategory.SubsidyEnabled == true, attendance date within the acceptance's [StartDate, EndDate], SubsidyTypeId != None.

Real-world example: A parent confirms a booking with subsidy intent → the system creates a Draft SubsidyAcceptance and updates SocialBenefitNumber → staff approves → Approved; estimation only runs with an Approved acceptance and attendance within the date range.

Subsidy vs Discount

	Subsidy	Discount
Source	Government	Merchant
Applied at	Invoice level	Booking line level
Code path	Independent	Independent
Stacking	N/A	Max 3 per type

The two concepts are completely orthogonal: no shared code path, no execution-order dependency.

Site licence setup (OSCAR / Alberta)

Only shown when SubsidyTypeId is NZ_OSCAR or CANADA_ALBERTA:

• Entry point — Settings > Finance > Subsidy shows a top-right button: Setup SWN (OSCAR) or Setup Program ID (Alberta).
• Setup page — lists the BU's active licences, add/edit/delete; create CTA in the shared form + New SWN / + New Program ID.
• Site binding — a licence may be unbound (Licence.OrgId = null) or bound to 1 site; each site has at most 1 active licence; changing site → clear the old OrgId before setting a new one.
• Site Subsidy Settings — the site's licence dropdown reads from Licence.OrgId = site, not OrgProgramCategory.SubsidyLicenceId; quick-create prefills OrgId = site but allows leaving it blank.

Real-world example: An OSCAR BU admin clicks Setup SWN → creates a new SWN not yet bound (OrgId = null) → opens Site Subsidy Settings of site S, selects that SWN → assigns Licence.OrgId = S; selecting another SWN clears the old licence and reassigns it.