BillingSubscription
A tenant's verified subscription: at most one row per tenant (V167's unique index on tenant_id), written only by provider webhooks.
| Table | billing_subscription |
| Tenant-scoped | No — global table |
| Columns | 26 |
| Relationships | 0 |
| Source | backend/src/main/java/com/motorph/payroll/model/BillingSubscription.java |
This entity does not extend TenantOwned, so its rows are shared across every tenant. TenantCoverageTest allows that only for tables deliberately declared global.
Columns
| Field | Type | Column | Null | Notes |
|---|---|---|---|---|
billingSubscriptionId | Integer | billing_subscription_id | — | primary key, generated |
tenantId | Integer | tenant_id | — | Set explicitly on insert -- the column has no default since V167, so forgetting it fails. |
provider | String | provider | — | — |
providerSubscriptionId | String | provider_subscription_id | Yes | — |
providerCustomerId | String | provider_customer_id | Yes | — |
planCode | String | plan_code | Yes | — |
status | SubscriptionStatus | status | — | converted by SubscriptionStatusConverter |
amount | BigDecimal | amount | Yes | — |
currency | String | currency | Yes | — |
currentPeriodEnd | LocalDateTime | current_period_end | Yes | — |
cancelAtPeriodEnd | boolean | cancel_at_period_end | — | — |
seats | Integer | seats | Yes | Seats (active employees) the current period bills for; null on a flat, pre-seat plan. |
pendingSeats | Integer | pending_seats | Yes | A lower seat count already scheduled to take effect at renewal; null when none is. |
pendingPlanCode | String | pending_plan_code | Yes | A plan scheduled to take over at renewal (a downgrade); null when none is. |
pendingChangeAt | LocalDateTime | pending_change_at | Yes | When #pendingPlanCode takes over (Manila time). |
seatsSyncedAt | LocalDateTime | seats_synced_at | Yes | — |
seatSyncFailure | SeatSyncFailure | seat_sync_failure | Yes | enum; Why the last seat change was refused; null when the last sync worked. |
seatSyncFailedSince | LocalDateTime | seat_sync_failed_since | Yes | — |
seatSyncFailedSeats | Integer | seat_sync_failed_seats | Yes | — |
seatSyncNotifiedAt | LocalDateTime | seat_sync_notified_at | Yes | — |
seatSyncRemindedAt | LocalDateTime | seat_sync_reminded_at | Yes | — |
seatsReportedAt | LocalDateTime | seats_reported_at | Yes | — |
createdBy | String | created_by | Yes | — |
createdDate | LocalDateTime | created_date | — | — |
lastModifiedBy | String | last_modified_by | Yes | — |
lastModifiedDate | LocalDateTime | last_modified_date | Yes | — |
Repository
BillingSubscriptionRepository
Every lookup names the tenant: the entity is not tenant-filtered (see BillingSubscription), so an unqualified query would read across companies whenever RLS is not in force.
Declared over BillingSubscription with id type Integer. Source: backend/src/main/java/com/motorph/payroll/repository/BillingSubscriptionRepository.java
| Method | Returns | Notes |
|---|---|---|
findByTenantId(Integer tenantId) | Optional<BillingSubscription> | derived |
findByProviderAndProviderSubscriptionId(String provider, String providerSubscriptionId) | Optional<BillingSubscription> | derived |
findByTenantIdForUpdate(@Param("tenantId") Integer tenantId) | Optional<BillingSubscription> | explicit @Query |
Reached by
These controllers hold — directly or through a service they depend on — a repository over BillingSubscription.
| Controller | Base path | Endpoints | Module |
|---|---|---|---|
| BillingController | /api/billing | 6 | Billing & Platform |
| BillingWebhookController | /api/webhooks | 1 | Billing & Platform |
| PublicBillingController | /api/public/billing | 1 | Billing & Platform |
| SubscriptionStatusController | /api/billing | 1 | Billing & Platform |
This page is rebuilt from the source on every docs build by docs-site/scripts/gen-code-wiki.mjs. Editing it has no effect — change the code, or, if what you want to say is prose, write it in docs/.