📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
Store historic Paddle invoices if user cancels & re-subscribes
Blue Mouse8d0d94a9211f
diff --git a/backend/apps/cloud/src/user/entities/user-subscription.entity.ts b/backend/apps/cloud/src/user/entities/user-subscription.entity.tsnew file mode 100644index 000000000..09049d846--- /dev/null+++ b/backend/apps/cloud/src/user/entities/user-subscription.entity.ts@@ -0,0 +1,51 @@+import {+ Column,+ CreateDateColumn,+ Entity,+ Index,+ JoinColumn,+ ManyToOne,+ PrimaryGeneratedColumn,+} from 'typeorm'++import { User } from './user.entity'++// Every Paddle subscription id a user has ever had. `user.subID` only holds the+// current one and is cleared once a cancellation lapses, and Paddle Classic+// mints a brand new subscription id when a churned customer comes back - so+// without this table the invoice history of cancelled and returning customers+// becomes permanently unreachable+@Entity()+@Index(['userId'])+@Index(['subID'], { unique: true })+export class UserSubscription {+ @PrimaryGeneratedColumn('uuid')+ id: string++ @Column('varchar', { length: 36 })+ userId: string++ @ManyToOne(() => User, { onDelete: 'CASCADE' })+ @JoinColumn({ name: 'userId' })+ user: User++ @Column('varchar', { length: 32 })+ subID: string++ // Paddle's customer id - unlike the subscription id it survives a resubscribe+ @Column('varchar', { length: 32, nullable: true })+ paddleUserId: string | null++ // Paddle plan (product) id the subscription was opened on+ @Column('varchar', { length: 16, nullable: true })+ planId: string | null++ @Column({ type: 'timestamp', nullable: true })+ startedAt: Date | null++ @Column({ type: 'timestamp', nullable: true })+ endedAt: Date | null++ @CreateDateColumn()+ createdAt: Date+}diff --git a/backend/apps/cloud/src/user/user.module.ts b/backend/apps/cloud/src/user/user.module.tsindex 9c985f8db..82484980b 100644--- a/backend/apps/cloud/src/user/user.module.ts+++ b/backend/apps/cloud/src/user/user.module.ts@@ -18,6 +18,7 @@ import { OrganisationModule } from '../organisation/organisation.module'import { UserAddon } from './entities/user-addon.entity'import { UserAddonCharge } from './entities/user-addon-charge.entity'import { SubscriptionDunning } from './entities/subscription-dunning.entity'+import { UserSubscription } from './entities/user-subscription.entity'@Module({imports: [@@ -30,6 +31,7 @@ import { SubscriptionDunning } from './entities/subscription-dunning.entity'UserAddon,UserAddonCharge,SubscriptionDunning,+ UserSubscription,Message,]),ActionTokensModule,diff --git a/backend/apps/cloud/src/user/user.service.ts b/backend/apps/cloud/src/user/user.service.tsindex dcd5dc5f8..393d06e68 100644--- a/backend/apps/cloud/src/user/user.service.ts+++ b/backend/apps/cloud/src/user/user.service.ts@@ -61,6 +61,7 @@ import {SubscriptionDunning,SubscriptionDunningStatus,} from './entities/subscription-dunning.entity'+import { UserSubscription } from './entities/user-subscription.entity'import { UserGoogleDTO } from './dto/user-google.dto'import { UserGithubDTO } from './dto/user-github.dto'import { EMAIL_ACTION_ENCRYPTION_KEY, redis } from '../common/constants'@@ -300,6 +301,8 @@ export class UserService {private readonly userAddonChargeRepository: Repository<UserAddonCharge>,@InjectRepository(SubscriptionDunning)private readonly subscriptionDunningRepository: Repository<SubscriptionDunning>,+ @InjectRepository(UserSubscription)+ private readonly userSubscriptionRepository: Repository<UserSubscription>,private readonly organisationService: OrganisationService,) {}@@ -1064,16 +1067,62 @@ export class UserService {return data.response || {}}- // Payments (receipts) for the currently authenticated user only: the- // subscription id is always read from the user's own DB record and is never- // accepted from the client+ private async fetchPaddleSubscriptionPayments(+ subID: string,+ ): Promise<UserPayment[]> {+ const numericSubID = Number(subID)+ const body = new URLSearchParams()+ body.set('vendor_id', String(Number(PADDLE_VENDOR_ID)))+ body.set('vendor_auth_code', PADDLE_API_KEY)+ body.set(+ 'subscription_id',+ Number.isFinite(numericSubID) ? String(numericSubID) : subID,+ )+ body.set('is_paid', '1')++ const res = await fetch(+ 'https://vendors.paddle.com/api/2.0/subscription/payments',+ {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body,+ signal: AbortSignal.timeout(PAYMENTS_FETCH_TIMEOUT_MS),+ },+ )+ const data = await res.json()++ if (!res.ok || !data?.success) {+ throw new Error(+ `Paddle payments request failed: ${JSON.stringify(data?.error || data)}`,+ )+ }++ return (data.response || []).map((payment: Record<string, any>) => ({+ id: Number(payment.id),+ date: String(payment.payout_date || ''),+ amount: Number(payment.amount) || 0,+ currency: String(payment.currency || 'USD'),+ isOneOff: Boolean(payment.is_one_off_charge),+ receiptUrl: payment.receipt_url ? String(payment.receipt_url) : null,+ }))+ }++ // Payments (receipts) for the currently authenticated user only: subscription+ // ids are always read from the user's own DB records and are never accepted+ // from the client. Receipts are collected across every subscription the user+ // has ever had, since `user.subID` is cleared on cancellation and a+ // resubscribe always gets a new subscription idasync getPayments(userId: string): Promise<UserPayment[]> {+ if (!PADDLE_VENDOR_ID || !PADDLE_API_KEY) {+ return []+ }+const user = await this.findOne({where: { id: userId },select: ['id', 'subID'],})- if (!user?.subID || !PADDLE_VENDOR_ID || !PADDLE_API_KEY) {+ if (!user) {return []}@@ -1088,56 +1137,60 @@ export class UserService {}}- const body = new URLSearchParams()- body.set('vendor_id', String(Number(PADDLE_VENDOR_ID)))- body.set('vendor_auth_code', PADDLE_API_KEY)- body.set('subscription_id', String(Number(user.subID)))- body.set('is_paid', '1')-- let res: Response- let data: any+ const subIDs = await this.getUserSubscriptionIDs(user.id, user.subID)- try {- res = await fetch(- 'https://vendors.paddle.com/api/2.0/subscription/payments',- {- method: 'POST',- headers: { 'Content-Type': 'application/x-www-form-urlencoded' },- body,- signal: AbortSignal.timeout(PAYMENTS_FETCH_TIMEOUT_MS),- },- )- data = await res.json()- } catch (reason) {- console.error(- '[ERROR] (getPayments) Paddle payments request failed:',- reason,- )- throw new ServiceUnavailableException('Failed to load payment history')+ if (_isEmpty(subIDs)) {+ return []}- if (!res.ok || !data?.success) {- console.error(- '[ERROR] (getPayments) Paddle payments request failed:',- JSON.stringify(data?.error || data),- )+ const results = await Promise.allSettled(+ subIDs.map((subID) => this.fetchPaddleSubscriptionPayments(subID)),+ )++ const payments: UserPayment[] = []+ const seenPaymentIds = new Set<number>()+ let failedCount = 0++ results.forEach((result, index) => {+ if (result.status === 'rejected') {+ failedCount += 1+ console.error(+ `[ERROR] (getPayments) Failed to load payments for subscription ${subIDs[index]}:`,+ result.reason,+ )+ return+ }++ result.value.forEach((payment) => {+ if (seenPaymentIds.has(payment.id)) {+ return+ }++ seenPaymentIds.add(payment.id)+ payments.push(payment)+ })+ })++ // one unreachable subscription must not hide the receipts that did load;+ // only a complete failure is worth surfacing to the user+ if (failedCount === _size(subIDs)) {throw new ServiceUnavailableException('Failed to load payment history')}- const payments: UserPayment[] = (data.response || [])- .map((payment: Record<string, any>) => ({- id: Number(payment.id),- date: String(payment.payout_date || ''),- amount: Number(payment.amount) || 0,- currency: String(payment.currency || 'USD'),- isOneOff: Boolean(payment.is_one_off_charge),- receiptUrl: payment.receipt_url ? String(payment.receipt_url) : null,- }))- .sort((a: UserPayment, b: UserPayment) => b.date.localeCompare(a.date))+ payments.sort((a, b) => b.date.localeCompare(a.date))- await redis- .set(cacheKey, JSON.stringify(payments), 'EX', PAYMENTS_CACHE_TTL_SECONDS)- .catch(() => null)+ // a partial result is not worth caching for an hour - the next request+ // should get another chance at the subscriptions that failed+ if (failedCount === 0) {+ await redis+ .set(+ cacheKey,+ JSON.stringify(payments),+ 'EX',+ PAYMENTS_CACHE_TTL_SECONDS,+ )+ .catch(() => null)+ }return payments}@@ -2821,6 +2874,11 @@ export class UserService {}await this.update(id, updateParams)+ await this.recordUserSubscription({+ userId: id,+ subID,+ planId: planID,+ })await this.refreshWebsiteAddonEntitlements(id)await this.refreshSessionReplayAddonEntitlements(id)}@@ -2912,6 +2970,138 @@ export class UserService {return bytes.toString(CryptoJS.enc.Utf8)}+ // Records a Paddle subscription id against a user so it survives the user's+ // `subID` being cleared on cancellation. Safe to call repeatedly: Paddle+ // retries webhooks and `subscription_updated` fires many times per+ // subscription. Never throws - losing a history row must not fail the+ // subscription flow that triggered it+ async recordUserSubscription(params: {+ userId: string+ subID: string | number | null | undefined+ paddleUserId?: string | number | null+ planId?: string | number | null+ startedAt?: Date | null+ }): Promise<void> {+ const { userId } = params+ const subID = params.subID ? String(params.subID) : null++ if (!userId || !subID) {+ return+ }++ const paddleUserId = params.paddleUserId+ ? String(params.paddleUserId)+ : null+ const planId = params.planId ? String(params.planId) : null++ try {+ const existing = await this.userSubscriptionRepository.findOne({+ where: { subID },+ })++ if (existing) {+ const update: Partial<UserSubscription> = {}++ // a subscription id belongs to exactly one Paddle checkout, so a+ // mismatch means the webhook resolved to a different user than we+ // recorded before - the webhook wins, but it is worth knowing about+ if (existing.userId !== userId) {+ console.error(+ `[ERROR] (recordUserSubscription) Subscription ${subID} moved from user ${existing.userId} to ${userId}`,+ )+ update.userId = userId+ }++ if (!existing.paddleUserId && paddleUserId) {+ update.paddleUserId = paddleUserId+ }++ if (!existing.planId && planId) {+ update.planId = planId+ }++ if (!existing.startedAt && params.startedAt) {+ update.startedAt = params.startedAt+ }++ if (!_isEmpty(update)) {+ await this.userSubscriptionRepository.update(existing.id, update)+ }++ return+ }++ await this.userSubscriptionRepository.save(+ this.userSubscriptionRepository.create({+ userId,+ subID,+ paddleUserId,+ planId,+ startedAt: params.startedAt || null,+ endedAt: null,+ }),+ )+ } catch (reason) {+ // a concurrent webhook retry may have inserted the same row in between+ const duplicate = await this.userSubscriptionRepository+ .findOne({ where: { subID } })+ .catch(() => null)++ if (duplicate) {+ return+ }++ console.error(+ `[ERROR] (recordUserSubscription) Failed to record subscription ${subID} for user ${userId}:`,+ reason,+ )+ }+ }++ async markUserSubscriptionEnded(+ subID: string,+ endedAt: Date | null,+ ): Promise<void> {+ if (!subID) {+ return+ }++ try {+ await this.userSubscriptionRepository.update(+ { subID },+ { endedAt: endedAt || new Date() },+ )+ } catch (reason) {+ console.error(+ `[ERROR] (markUserSubscriptionEnded) Failed to mark subscription ${subID} as ended:`,+ reason,+ )+ }+ }++ // Every Paddle subscription id known for a user, current one first+ async getUserSubscriptionIDs(+ userId: string,+ currentSubID?: string | null,+ ): Promise<string[]> {+ const subscriptions = await this.userSubscriptionRepository.find({+ where: { userId },+ select: ['subID', 'startedAt', 'createdAt'],+ order: {+ startedAt: 'DESC',+ createdAt: 'DESC',+ },+ })++ return Array.from(+ new Set(+ [currentSubID, ...subscriptions.map(({ subID }) => subID)].filter(+ Boolean,+ ),+ ),+ )+ }+getOpenSubscriptionDunning(userId: string,): Promise<SubscriptionDunning | null> {diff --git a/backend/apps/cloud/src/webhook/webhook.controller.ts b/backend/apps/cloud/src/webhook/webhook.controller.tsindex fc980a938..eafee2e06 100644--- a/backend/apps/cloud/src/webhook/webhook.controller.ts+++ b/backend/apps/cloud/src/webhook/webhook.controller.ts@@ -726,6 +726,18 @@ export class WebhookController {}await this.userService.update(currentUser.id, updateParams)+ await this.userService.recordUserSubscription({+ userId: currentUser.id,+ subID,+ paddleUserId: this.getPaddleField(body, ['user_id']),+ planId: subscriptionPlanId,+ // only `subscription_created` carries the real start of the+ // subscription; an update's event_time would be misleading+ startedAt:+ body.alert_name === 'subscription_created'+ ? this.getPaddleCreatedAt(body)+ : null,+ })await this.userService.refreshWebsiteAddonEntitlements(currentUser.id)await this.userService.refreshSessionReplayAddonEntitlements(currentUser.id,@@ -755,6 +767,10 @@ export class WebhookController {nextBillDate: null,cancellationEffectiveDate,})+ await this.userService.markUserSubscriptionEnded(+ subID,+ this.getPaddleDate(body, ['cancellation_effective_date']),+ )await this.userService.resolveSubscriptionDunningsBySubID(subID,SubscriptionDunningStatus.cancelled,@@ -841,6 +857,15 @@ export class WebhookController {return}+ // safety net: a paid subscription whose `subscription_created` never+ // landed would otherwise leave its receipts unreachable forever+ await this.userService.recordUserSubscription({+ userId: subscriber.id,+ subID,+ paddleUserId: this.getPaddleField(body, ['user_id']),+ planId: this.getPaddleField(body, ['subscription_plan_id']),+ })+const dunning = await this.userService.getOpenSubscriptionDunning(subscriber.id,)diff --git a/backend/migrations/mysql/2026_07_25_user_subscriptions.sql b/backend/migrations/mysql/2026_07_25_user_subscriptions.sqlnew file mode 100644index 000000000..f9fca5066--- /dev/null+++ b/backend/migrations/mysql/2026_07_25_user_subscriptions.sql@@ -0,0 +1,21 @@+-- Historic Paddle subscription ids per user.+--+-- `user.subID` holds only the current subscription and is nulled by+-- cleanUpUnpaidSubUsers once a cancellation period lapses; Paddle Classic also+-- issues a new subscription id whenever a churned customer resubscribes. Both+-- severed the link to /subscription/payments, hiding the entire invoice history+-- of cancelled and returning customers.+CREATE TABLE `user_subscription` (+ `id` varchar(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,+ `userId` varchar(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,+ `subID` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,+ `paddleUserId` varchar(32) DEFAULT NULL,+ `planId` varchar(16) DEFAULT NULL,+ `startedAt` timestamp NULL DEFAULT NULL,+ `endedAt` timestamp NULL DEFAULT NULL,+ `createdAt` datetime(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),+ PRIMARY KEY (`id`),+ UNIQUE KEY `IDX_user_subscription_sub` (`subID`),+ KEY `IDX_user_subscription_user` (`userId`),+ CONSTRAINT `FK_user_subscription_user` FOREIGN KEY (`userId`) REFERENCES `user` (`id`) ON DELETE CASCADE+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;diff --git a/backend/scripts/backfill-user-subscriptions.js b/backend/scripts/backfill-user-subscriptions.jsnew file mode 100644index 000000000..ea6388999--- /dev/null+++ b/backend/scripts/backfill-user-subscriptions.js@@ -0,0 +1,246 @@+/**+ * Backfills the `user_subscription` table from Paddle.+ *+ * Existing users have no subscription history rows, so every subscription that+ * predates the table has to come from Paddle itself. Subscriptions are matched+ * to users by email, which is the only key Paddle's Classic API exposes on the+ * subscription list.+ *+ * Known weakness: a user who changed their Swetrix email after subscribing will+ * not match, and their invoice history stays hidden. Those are reported as+ * unmatched at the end. Going forward the webhooks record `paddleUserId`, which+ * is stable across resubscribes and email changes.+ *+ * Usage (dry run, writes nothing):+ * node scripts/backfill-user-subscriptions.js+ *+ * Usage (actually insert):+ * node scripts/backfill-user-subscriptions.js --apply+ */++const path = require('path')+const crypto = require('crypto')+const mysql = require('mysql2/promise')++require('dotenv').config({ path: path.join(__dirname, '..', '.env') })++const APPLY = process.argv.includes('--apply')+const RESULTS_PER_PAGE = 200+const PADDLE_STATES = ['active', 'past_due', 'trialing', 'deleted']+const PADDLE_TIMEOUT_MS = 30_000++const {+ PADDLE_VENDOR_ID,+ PADDLE_API_KEY,+ MYSQL_HOST,+ MYSQL_USER,+ MYSQL_ROOT_PASSWORD,+ MYSQL_DATABASE,+} = process.env++const fetchPaddleSubscriptionsPage = async (state, page) => {+ const body = new URLSearchParams()+ body.set('vendor_id', String(Number(PADDLE_VENDOR_ID)))+ body.set('vendor_auth_code', PADDLE_API_KEY)+ body.set('state', state)+ body.set('page', String(page))+ body.set('results_per_page', String(RESULTS_PER_PAGE))++ const res = await fetch('https://vendors.paddle.com/api/2.0/subscription/users', {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body,+ signal: AbortSignal.timeout(PADDLE_TIMEOUT_MS),+ })+ const data = await res.json()++ if (!res.ok || !data?.success) {+ throw new Error(+ `Paddle subscription list failed (state=${state}, page=${page}): ${JSON.stringify(+ data?.error || data,+ )}`,+ )+ }++ return data.response || []+}++const fetchAllPaddleSubscriptions = async () => {+ const subscriptions = new Map()++ for (const state of PADDLE_STATES) {+ let page = 1++ // the default listing omits deleted subscriptions, so every state has to be+ // paged through separately+ for (;;) {+ const results = await fetchPaddleSubscriptionsPage(state, page)++ results.forEach((subscription) => {+ subscriptions.set(String(subscription.subscription_id), {+ subID: String(subscription.subscription_id),+ email: String(subscription.user_email || '').trim(),+ paddleUserId: subscription.user_id+ ? String(subscription.user_id)+ : null,+ planId: subscription.plan_id ? String(subscription.plan_id) : null,+ startedAt: subscription.signup_date || null,+ endedAt: subscription.cancellation_effective_date || null,+ state,+ })+ })++ console.log(+ ` paddle: state=${state} page=${page} -> ${results.length} subscription(s)`,+ )++ if (results.length < RESULTS_PER_PAGE) {+ break+ }++ page += 1+ }+ }++ return Array.from(subscriptions.values())+}++const main = async () => {+ if (!PADDLE_VENDOR_ID || !PADDLE_API_KEY) {+ throw new Error('PADDLE_VENDOR_ID / PADDLE_API_KEY are not set')+ }++ console.log(+ APPLY+ ? 'Running in APPLY mode - rows will be inserted'+ : 'Running in DRY RUN mode - nothing will be written (pass --apply to insert)',+ )++ console.log('\nFetching subscriptions from Paddle...')+ const subscriptions = await fetchAllPaddleSubscriptions()+ console.log(`Fetched ${subscriptions.length} distinct subscription(s)`)++ const connection = await mysql.createConnection({+ host: MYSQL_HOST,+ port: 3306,+ user: MYSQL_USER,+ password: MYSQL_ROOT_PASSWORD,+ database: MYSQL_DATABASE,+ timezone: 'Z',+ })++ try {+ // Paddle reports every date in UTC and they are inserted as literal+ // strings, so the session has to interpret them as UTC too+ await connection.query("SET time_zone = '+00:00'")++ const [users] = await connection.query('SELECT `id`, `email` FROM `user`')+ const usersByEmail = new Map(+ users+ .filter(({ email }) => !!email)+ .map(({ id, email }) => [email.trim().toLowerCase(), id]),+ )++ let existingRows = []++ try {+ ;[existingRows] = await connection.query(+ 'SELECT `subID` FROM `user_subscription`',+ )+ } catch (reason) {+ // a dry run is useful before the migration has been applied; an apply is not+ if (reason.code !== 'ER_NO_SUCH_TABLE' || APPLY) {+ throw reason+ }++ console.log(+ '\nNote: `user_subscription` does not exist yet - run migrations/mysql/2026_07_25_user_subscriptions.sql before --apply.',+ )+ }++ const existing = new Set(existingRows.map(({ subID }) => subID))++ const toInsert = []+ const unmatched = []++ subscriptions.forEach((subscription) => {+ const userId = usersByEmail.get(subscription.email.toLowerCase())++ if (!userId) {+ unmatched.push(subscription)+ return+ }++ toInsert.push([+ crypto.randomUUID(),+ userId,+ subscription.subID,+ subscription.paddleUserId,+ subscription.planId,+ subscription.startedAt,+ subscription.endedAt,+ subscription.email,+ ])+ })++ const fresh = toInsert.filter(([, , subID]) => !existing.has(subID))++ console.log(`\nMatched to a user: ${toInsert.length}`)+ console.log(` already recorded: ${toInsert.length - fresh.length}`)+ console.log(` to insert: ${fresh.length}`)++ fresh.forEach(([, userId, subID, , , startedAt, endedAt, email]) => {+ console.log(+ ` + ${subID} ${email} user=${userId} started=${startedAt || '?'}${+ endedAt ? ` ended=${endedAt}` : ''+ }`,+ )+ })++ if (unmatched.length > 0) {+ console.log(+ `\nNo Swetrix user matches these ${unmatched.length} subscription(s) - most are deleted accounts, the rest are users who changed their email after subscribing:`,+ )+ unmatched.forEach(({ subID, email, state }) => {+ console.log(` ? ${subID} ${email || '<no email>'} state=${state}`)+ })+ }++ if (!APPLY) {+ console.log('\nDry run complete, nothing was written.')+ return+ }++ if (toInsert.length === 0) {+ console.log('\nNothing to insert.')+ return+ }++ // every matched subscription goes through the same statement: rows that+ // already exist only get their empty columns filled in, so this is+ // rerunnable and never overwrites richer data written by the webhooks+ await connection.query(+ 'INSERT INTO `user_subscription` (`id`, `userId`, `subID`, `paddleUserId`, `planId`, `startedAt`, `endedAt`) VALUES ? ' ++ 'ON DUPLICATE KEY UPDATE `paddleUserId` = COALESCE(`paddleUserId`, VALUES(`paddleUserId`)), ' ++ '`planId` = COALESCE(`planId`, VALUES(`planId`)), ' ++ '`startedAt` = COALESCE(`startedAt`, VALUES(`startedAt`)), ' ++ '`endedAt` = COALESCE(`endedAt`, VALUES(`endedAt`))',+ [toInsert.map((row) => row.slice(0, 7))],+ )++ const [[{ total }]] = await connection.query(+ 'SELECT COUNT(*) AS total FROM `user_subscription`',+ )++ console.log(+ `\nInserted ${fresh.length} new row(s); ${total} subscription(s) recorded in total.`,+ )+ } finally {+ await connection.end()+ }+}++main().catch((reason) => {+ console.error(reason)+ process.exit(1)+})