Billing entities

[jace]

Funnel currently does not offer ticketing or other forms of sales, but Boxoffice does, and that project is pending merger into Funnel. One sticky point is with the concept of a billing entity.

Projects are not legal entities, and the profile hosting the project may not be a legal entity either. It could be a brand owned by a legal entity, or one that has no clear ownership (such as a meetup group, with a steward rather than owner). Legal entity for our purposes is a "billing entity" that collects or makes payments and is accountable in the tax system, and so can be tagged with its tax identifiers (PAN and GST in India). This requirement also comes up when offering tickets on sale. A weak billing entity concept already exists in Boxoffice: https://github.com/hasgeek/boxoffice/pull/198

A billing entity is very much like the present Organization model, but not all organizations (or profiles) are billing entities. Several brand profiles may be collated under one billing entity. It makes sense to build this into a distinct model, but not to create distinct role access controls, as that is both tech overhead and confusion for users.

1. A billing entity as a distinct model could have one primary relationship with a profile that it gets access controls from, and several inbound relationships from brand profiles that use it. However, this creates a bi-directional foreign key loop, which previously was a pain point with the "Owners" special team (before its replacement with a role in #401).

2. A billing entity could have a tighter bind to a profile, creating either a 1:1 relationship or including it in the Profile model itself. Other profiles can then refer to this profile as their billing entity (with caveats, see next two).

3. Brands change ownership over time. The reference to a billing entity should be versioned, making it yet another instance of a membership model (a secondary model between a profile and its billing entity).

4. However, billing entities need long term access to records (minimum 7 years in India), so when an profile switches from one billing entity to another, there still has to be a way for the previous billing entity to access financial records. This requires a more explicit (and immutable) link to the specific transactions, which currently reside in a project. This means a link from project to billing entity is far more important than one from its host profile.

5. Individuals can be billing entities, but our model does not provide shared role access to user accounts, from an explicit decision to discourage organizations from signing up with user accounts (as activity within that account cannot be attributed to a specific actor). However, individuals who are billing entities often do outsource financial management to an accountant, which requires granting access to the account. This means we have to pick one of either:

   • Relocate role access from the Organization model to the Profile model. In this case, OrganizationMembership (renamed to ProfileMembership) can be augmented with a new role column is_accountant or is_finance that only appears in the UI when the org hosts a billing entity (for user accounts, it's always set). Implementation detail: this will require an additional is_admin column, as the admin role is no longer implicit: an accountant may not be an admin. OrganizationMembership at present grants an automatic admin role to whoever is the subject of the membership record. An is_owner column also grants owner role, which has the power to appoint and dismiss other admins and owners.

   • Add separate role access to the billing entity model, as there is a distinct role for accessing financial records, but user accounts must also be clearly distinct from organizations. There is a case for three billing entity roles: owner (possibly acquired from profile), accountant and auditor (read-only access).

6. The problem with a distinct billing entity is that it has no clear identifier like a username, so there's a risk of two brands within the same legal entity registering as two separate billing entities and not being aware of it. This already happens a lot with regular user accounts, where the same user fails to realize that they already have an account. We can help avoid this a bit by always referring to a billing entity via the host Profile.

[jace]

Another wrinkle: billing entities may themselves need to be versioned as tax regimes and identifiers change over time, and companies can rename themselves, but the historical details matter for tax purposes. This will be a possible BillingMembership and will require require parking access controls directly within Profile (as a possible BillingUserMembership). Profiles are not versioned and name (@name) and title (display name) can change at will with no historical record.

Creating a revision has a complication: what happens to the existing transactions? Do they refer to the updated entity or the historical one? Should the user be asked?

[jace]

In the Indian GST regime, a company may have a separate GST number for each of the states/UTs it operates in, and a different one may apply in each transaction depending on the other party's billing address. That means a billing entity is not a serial membership where each new record archives the previous, but a parallel system of records where each record may be archived and unarchived at will.

Commercial offerings (like tickets) cannot link directly to these individual records, but transactions must.