Working release guide — not a live billing system. The current prototype does not take payments, create invoices, enforce paid access, or connect to Apple, Google, PayPal, or a bank. Use fictional test entitlements only.
Store-policy assumptions were rechecked on 21 August 2026 against Apple’s guidelines updated 8 June 2026 and Google Play’s current payments and US-program notices. These rules are region-, storefront-, programme-, and product-specific; recheck them immediately before design approval and submission.
Use this guide to make the commercial, legal, product, support, and technical decisions that must precede any payment-provider connection. A provider account is one of the final steps, not the subscription model itself.
Decision Summary
The safest initial product shape is:
- a School plan for a school or instrumental music programme;
- a Studio plan for an independent teacher or small home studio;
- Teacher and Student (product label Player Account) as account roles, not separate copies of school data;
- Student (Player Account) access included by assignment from a subscribing school or studio, rather than sold directly to children in the first release;
- one server-owned entitlement for each subscribing organisation;
- no card details, bank details, or store credentials stored by Band Licence;
- one provider adapter at a time, beginning in a sandbox;
- manual invoicing kept separate from automated recurring subscriptions; and
- safe read-only access, export, correction, support, and deletion after an entitlement stops.
This is a recommendation for implementation order, not a final pricing decision. Pricing, tax treatment, contracting party, trial length, refunds, school procurement, and sales channel still require business and legal approval.
Current App Position
| Capability | Current state | Evidence in the app | Release meaning |
|---|---|---|---|
| School entitlement record | Built as a release-test scaffold | school_subscription_entitlements stores status, plan, billing owner, dates, limits and non-secret future provider references | Useful for fake-state testing only |
| Entitlement editing | Built for Administrators in School Settings | Status, owner, trial and period dates, school, teacher, and student limits | Does not charge money |
| Status calculation | Built as pure release-test rules | Trial dates, active, grace-period, cancelled-period end, expired, and suspended are recognised and tested | Provider reconciliation is not built |
| Student-free audience rule | Built as a release-test rule | Student access follows the school entitlement, never exposes billing controls, never requires a student email, and never charges a student individually | Not yet a production access gate |
| Audit/provider inbox | Scaffold built | Manual updates are audited; idempotent provider-event and checkout-session tables exist | No event adapter is enabled |
| Paid-access enforcement | Rules and access scaffold built | Shared student entry requires an allowing entitlement in account-beta/public-production; the local pilot remains available | Teacher-wide read-only enforcement still requires an approved commercial policy before activation |
| Subscription & access page | Built | Shows school status, adult-paid/student-free boundary, and manages revocable family access codes | No checkout, invoice, refund, or cancellation control is presented |
| Provider connection | Deliberately not enabled | Future provider/customer/subscription references and event records exist, but no provider, secret, webhook or payment collection is connected | Obtain commercial/privacy/store approval first |
| Tax invoices and receipts | Not built | No invoice number, GST, ABN, or accounting export workflow | Requires business decision and accounting review |
The current helper allows a local school with no entitlement to keep working. This is intentional for the local pilot. The release-test record must not silently become a production access decision.
Implemented access-code foundation
- Adult teacher onboarding is currently an Administrator-created, school-scoped, email-bound, expiring, single-use invitation link. Treat that secure invitation as the current teacher-access-code scaffold; do not weaken it into a reusable bare school code.
- Student access remains a teacher-issued barcode/QR credential followed by the student’s own four-digit security code. Students do not need an email address.
- A secure Teacher or Administrator can rotate or revoke an expiring, family-shareable school code. Only its HMAC digest is stored.
/joinpairs it with one active same-school licence card, returns no roster identity, and creates only the locked temporary session before the PIN step. - Open teacher self-registration, subscription checkout, and public school creation remain deliberately disabled until account beta, verified delivery/recovery, support, school approval, commercial, and abuse-prevention gates pass. Teacher sign-up remains the complete school-scoped invitation workflow.
Keep Four Concepts Separate
Many billing failures begin by treating an account, a plan, a payment, and access as the same record. Band Licence should keep these concepts separate.
| Concept | Answers | Example |
|---|---|---|
| Account role | What may this person do? | Administrator, Teacher, Student (Player Account), Read-only |
| Commercial plan | What has the customer purchased? | School, Studio, trial, extra teacher seats |
| Entitlement | What access is allowed now? | Active until date, grace period, read-only |
| Provider transaction | What happened financially? | Invoice paid, renewal failed, refund issued |
A Student role (product label Player Account) must not acquire Administrator access because a payment succeeded. A cancelled payment must not delete a school. Changing payment providers must not create a second school record.
Customer and Plan Decisions
Record a signed decision for every row before building checkout.
| Decision | Recommended starting position | Owner | Evidence required |
|---|---|---|---|
| Contracting customer | School or adult studio owner | Business owner | Approved customer definition |
| School plan | One organisation with configurable teacher and student limits | Product and finance | Plan sheet and limit rules |
| Studio plan | One adult teacher with optional assistants and assigned Student (Player Account) users | Product and finance | Studio workflow test |
| Student (Player Account) access | Included and assigned; no direct child purchase initially | Safeguarding and product | Child-access approval |
| Parent/carer access | Out of current scope | Product and school | Later role and consent review |
| Trial | No payment method until the trial design and reminders are approved | Business and legal | Trial wording and expiry tests |
| Renewal | Explicit recurring term, price, frequency, and next charge date | Finance and legal | Checkout and receipt copies |
| Cancellation | Effective at the stated time with an easy online path | Support and legal | End-to-end cancellation test |
| Refunds | Human-reviewed policy with provider-specific execution | Finance and support | Refund authority matrix |
| School transfer | Data stays with the school; access follows authorised roles | School and privacy owner | Transfer/offboarding runbook |
Do not use “Teacher Account” and “Player Account” as pricing names until the role model is stable. In the access model, Student is the future database role and Player Account is its product label; they are not separate roles. One teacher may work across several schools, and one school may have several teachers. Entitlements belong to the contracting organisation; people receive role-scoped access to that organisation.
Entitlement Contract
The Band Licence server, not the browser and not a payment-success screen, must make the access decision. A future entitlement record should include:
- stable organisation and plan identifiers;
- status and status reason;
- effective start, current period end, grace end, and cancellation effective time;
- plan limits and separately granted exceptions;
- provider name plus non-secret customer, subscription, and product references;
- provider event cursor or last reconciled time;
- billing owner and support contact references;
- source of the latest change: Administrator test, webhook, reconciliation, or support override;
- created, updated, and last-verified timestamps; and
- an immutable audit reference for each change.
Never store a full card number, card security code, bank credential, Apple or Google account password, payment-provider secret, or raw webhook secret in the database or audit log.
Status Model and Access Decisions
| Entitlement state | Normal access | Billing controls | Data and support access | Required action |
|---|---|---|---|---|
| No release entitlement | Local pilot only; production blocks launch | Administrator only | Export, support, correction, deletion | Establish contract or approved free access |
| Trial | Full plan access within limits | Billing owner and Administrator | Full | Show exact trial end and what happens next |
| Active | Full plan access within limits | Billing owner and Administrator | Full | Reconcile provider state regularly |
| Grace period | Temporary continued access | Billing owner and Administrator | Full | Explain payment issue without blaming the user |
| Cancelled, period active | Full access until the confirmed end | Billing owner and Administrator | Full | Show end date and reversal path if available |
| Expired | Safe read-only school access | Billing owner and Administrator | Export, support, correction, deletion | Restore or complete offboarding |
| Suspended | Safe read-only unless suspension is a security containment | Administrator and support | Export/deletion unless legally restricted | Record reason, authority, review date |
An expired or cancelled entitlement must never erase school data. Attendance, safety, correction, access review, export, and deletion pathways remain available according to role. If security or legal containment requires narrower access, record the authority and give the customer a support route.
Date and time rules
- Store provider times as precise timestamps, not date-only strings.
- Display customer-facing times in
Australia/Brisbaneunless the contract uses another stated zone. - Treat trial end, renewal, grace, cancellation, and deletion as different events.
- Never infer payment success merely because a period-end date is in the future.
- Do not extend access from an unverified browser redirect.
Provider Adapter Boundary
Every payment channel should translate its events into one internal entitlement command. Provider-specific terms must not leak across the rest of the app.
| Adapter responsibility | Rule |
|---|---|
| Verify authenticity | Verify signatures or use the provider's supported event-verification mechanism before changing access |
| Deduplicate | Persist the provider event identifier and make repeated delivery harmless |
| Order events | Compare provider event time/version; do not let an old failure overwrite a later recovery |
| Map states | Keep a documented provider-to-Band-Licence state table |
| Reconcile | Fetch current provider state on a schedule and after ambiguous events |
| Fail safely | Queue or retry transient failures without granting unverified access |
| Audit | Record event type, provider reference, result, and actor/system source without sensitive payloads |
| Observe | Alert on verification failure, backlog, repeated delivery, state mismatch, and reconciliation age |
The browser may display “payment submitted”, but only a verified server event or verified provider query may activate access.
Channel Strategy
Direct school invoice
This is often the simplest school purchasing path, but it still needs:
- legal business name, ABN and GST position;
- unique invoice and credit-note numbers;
- purchase order and accounts-payable fields where required;
- clear service period and plan description;
- payment allocation and overdue process;
- receipt or tax-invoice rules confirmed with an accountant;
- cancellation, refund, dispute, and support contacts; and
- separation between financial records and school/student records.
Do not place student names on invoices.
PayPal web subscription or invoice
- use hosted provider approval rather than collecting payment details;
- verify webhook messages and make handlers idempotent;
- maintain a provider-event inbox and reconciliation job;
- use sandbox accounts and fictional customers until final approval;
- map activation, renewal, failed payment, suspension, cancellation, expiry, refund, and reversal explicitly; and
- keep invoice email delivery disabled until the communications and privacy owner approves it.
Apple Pay on the web
Apple Pay is a payment method, not a subscription ledger. A production setup needs a Merchant ID, certificates, verified web domain, supported payment processor, server-created merchant session, and certificate renewal ownership. Recurring-payment terms must clearly describe what is supplied, the renewal term, the amounts and timing, and cancellation.
App Store and Google Play
Native-store billing rules depend on what is sold, where it is consumed, the storefront, and current programme eligibility. Do not assume a school invoice exempts a consumer native app or that web checkout may always be linked from the app. Obtain store-policy review immediately before implementation and submission.
Apple’s current rules still require careful classification of digital subscription access and clear subscription terms. Google Play’s standard policy requires Play Billing for paid in-app digital access unless a stated exception or enrolled regional programme applies; its 2026 US alternative-billing and external-link changes do not create a global exemption. Keep purchase links and real products out of the prototype until the distribution regions and approved programme are recorded.
The entitlement service should prevent duplicate charging across web and stores by linking provider purchases to one organisation entitlement. It must never merge organisations merely because billing emails match.
Cancellation, Refunds, and Failed Payments
The customer-facing flow should answer five questions without opening a support ticket:
- What plan is active?
- What is the exact price and billing frequency?
- When is the next charge or access end?
- How do I cancel or manage the subscription?
- What happens to school access and data after cancellation?
Cancellation should be at least as easy to find as upgrade. For an online contract, design an online cancellation path now. The Australian unfair-trading reforms enacted in 2026 include specific subscription and digital-interface requirements that commence on 1 July 2027. Final legal review is required before launch and again before that commencement date.
Failed payment handling must:
- avoid exposing failure details to Players or unrelated Teachers;
- show a neutral message to the billing owner;
- allow provider recovery during a defined grace period;
- avoid repeated email or in-app harassment;
- restore access automatically only after verified recovery;
- preserve data and offboarding routes after expiry; and
- provide a support escalation when provider and app states disagree.
Consumer, Contract, and Tax Review
Before selling anything, obtain Australian legal and accounting review covering:
- customer identity and authority to bind a school or business;
- Australian Consumer Law guarantees and remedies;
- unfair contract terms and unfair trading practices;
- clear recurring-payment, renewal, trial, cancellation, and refund disclosures;
- GST registration, prices inclusive of GST, tax invoices, and credit notes;
- school procurement, purchase orders, and records retention;
- privacy disclosures for payment-provider data sharing;
- chargebacks and disputed transactions;
- minors and the decision not to sell directly to children initially; and
- cross-border taxes and store terms if sales expand beyond Australia.
This guide is an implementation checklist, not legal, tax, or accounting advice.
Billing Roles and Separation of Duties
| Action | Billing owner | School Administrator | Teacher | Student (Player Account) | Support/finance |
|---|---|---|---|---|---|
| View plan and renewal date | Yes | Yes | Summary only if approved | No | Scoped support view |
| Change payment method | Yes | Optional by policy | No | No | No direct credential access |
| Change plan | Yes | Optional by policy | No | No | Approved assisted change |
| Cancel | Yes | Optional by policy | No | No | Approved assisted cancellation |
| Export school data | Role-dependent | Yes | School policy | Own approved data only | No by default |
| Issue refund | No | No | No | No | Authorised finance role |
| Override entitlement | No | No | No | No | Dual-authorised, time-limited, audited |
No one should be able to edit provider references, issue a refund, and erase the audit trail. Support impersonation is not an acceptable shortcut.
Audit and Evidence
Record these events without storing card or bank details:
- trial created, extended, converted, or ended;
- subscription activated, renewed, changed, cancelled, expired, suspended, or restored;
- payment failed or recovered;
- refund or chargeback state received;
- billing owner changed;
- plan limit or exception changed;
- read-only access applied or lifted;
- provider event rejected, repeated, delayed, or reconciled;
- manual override created, reviewed, expired, or revoked; and
- customer export, offboarding, correction, or deletion request linked to subscription closure.
Evidence for a release should include sandbox receipts, signed event fixtures, duplicate and out-of-order event results, reconciliation output, access screenshots for every role, cancellation proof, refund proof, incident rehearsal results, and an approved customer-support script.
Test Matrix
| Scenario | Expected result |
|---|---|
| Checkout redirect without verified event | No entitlement change |
| Same verified webhook delivered repeatedly | One audit outcome; no duplicated access or invoice |
| Older cancellation arrives after a renewal | Reconciliation preserves the provider's current authoritative state |
| Payment fails during grace | Access continues only until the defined grace end |
| Grace expires | School moves to safe read-only; data remains available for export/support/deletion |
| Cancel at period end | Exact end is shown; access continues until then |
| Immediate approved refund | Provider and entitlement state reconcile; outcome is audited |
| Billing owner leaves the school | Administrator follows reassignment process; no orphaned subscription |
| Teacher belongs to two schools | Each organisation's entitlement is evaluated independently |
| Provider unavailable | Existing verified entitlement is not destroyed; retry and alert activate |
| Forged or malformed event | Rejected without access change; security event recorded safely |
| Student (Player Account) opens billing route | Billing detail remains hidden |
| Expired school requests export/deletion | Authorised pathway remains available |
Implementation Sequence
- Approve customer, plan, role, cancellation, refund, tax, and support decisions.
- Replace date-only release-test fields with a versioned production entitlement contract where needed.
- Enforce entitlement decisions centrally on server actions and API routes using fictional states.
- Build the safe read-only, export, correction, support, and deletion experience.
- Add immutable billing audit detail and time-limited manual overrides.
- Implement one provider adapter, verified event inbox, deduplication, retry, and reconciliation.
- Exercise all states in provider sandbox with fictional organisations.
- Complete privacy, security, consumer-law, tax, school-procurement, and accessibility review.
- Run a staff-only billing beta with monitoring and rollback.
- Enable real charging only after an authorised release owner signs the evidence pack.
Release Gate
- Contracting customer and first plan are approved.
- Teacher, Student (Player Account), Administrator, billing-owner, finance, and support responsibilities are approved.
- Price, GST, invoice, renewal, trial, cancellation, refund, and failed-payment wording is approved.
- Entitlement checks cover every protected server action and API route.
- Expired access is safe, comprehensible, and preserves export, support, correction, and deletion.
- Provider verification, deduplication, retry, reconciliation, and monitoring tests pass.
- No payment credential or sensitive provider payload is stored or logged.
- Cross-channel duplicate charging is prevented.
- Sandbox purchase, renewal, failure, recovery, cancellation, refund, and restore are evidenced.
- Privacy, security, consumer-law, tax, accounting, school-procurement, and store reviews are signed.
- Support can resolve a provider/app mismatch without editing the database directly.
- Rollback can disable new purchases without removing existing verified access.
Until every applicable item is evidenced, keep the current panel labelled release-test entitlement, keep real payment controls absent, and do not claim subscription readiness.
Authoritative References
- Apple App Review Guidelines
- Apple auto-renewable subscriptions
- Google Play subscription policy
- Google Play payments policy
- Google Play 2026 US policy-program notice
- PayPal subscription webhooks
- PayPal webhook verification
- Apple Pay on the web diagnostics and configuration
- ACCC contracts guidance
- ACCC consumer guarantees
- Australian Taxation Office GST definitions
- Competition and Consumer Amendment (Unfair Trading Practices) Act 2026
- Account and Data Deletion
- Terms of Use Draft
- Privacy Policy Draft
- App Store and Play Store Readiness