Contract: Current-Plan API Extension (optional, additive)
Existing endpoint: Supplier “current plan” resource (user app), documented in
yoyacoo_fe/swagger/api/supplier/paths/subscription/ + components/_subscription.yaml, backed by
user/app/Domains/Subscription/Usecase/CurrentPlanInteractor.php →
user/app/Domains/Subscription/Controller/Resource/CurrentPlanResource.php.
Change: add two nullable/optional fields to the existing response object — no new endpoint, no
breaking change to existing fields.
| Field | Type | Description |
|---|---|---|
requires_repayment |
boolean | true when the subscriber’s current payment is PAST_DUE (i.e., in the grace period and needs to update/retry payment) |
hosted_invoice_url |
string, nullable | The Stripe-hosted payment link to show/link to in-app when requires_repayment is true; null otherwise |
Status: This is not required by the spec’s functional requirements (the 3 dunning + 1
success email already carry the payment link directly to the subscriber — no in-app UI is
mandated). It is included here only because the reference implementation exposes it as a low-cost
addition that lets the existing supplier subscription screen optionally show a “payment required”
banner. Treat as optional scope for the tasks phase: implement only if the user wants an in-app
indicator in addition to the emails; otherwise this contract can be dropped without affecting any
FR/SC in spec.md.
If implemented, per constitution principle II (API-First & Contract-Driven), the OpenAPI spec
component (yoyacoo_fe/swagger/api/supplier/components/_subscription.yaml) must be updated and the
supplier API client regenerated (./crage codegen:supplier) in the same change — the generated
client in src/apis/clients/ must never be hand-edited.