@stamhoofd/backend 2.130.0 → 2.131.0

package/src/endpoints/global/registration/RegisterMembersEndpoint.ts

@@ -5,7 +5,7 @@ import { Endpoint, Response } from '@simonbackx/simple-endpoints';
 import { SimpleError } from '@simonbackx/simple-errors';
 import { Email } from '@stamhoofd/email';
 import type { MemberWithUsersRegistrationsAndGroups, Organization, Payment } from '@stamhoofd/models';
-import { BalanceItem, CachedBalance, Group, Member, Platform, RateLimiter, Registration } from '@stamhoofd/models';
+import { BalanceItem, CachedBalance, Group, Member, Platform, RateLimiter, Registration, RegistrationPeriod } from '@stamhoofd/models';
 import type { BalanceItem as BalanceItemStruct, PlatformMember, RegisterItem } from '@stamhoofd/structures';
 import { BalanceItemRelation, BalanceItemRelationType, BalanceItemStatus, BalanceItemType, IDRegisterCheckout, Payment as PaymentStruct, PermissionLevel, PlatformFamily, ReceivableBalanceType, RegisterResponse, TranslatedString } from '@stamhoofd/structures';
 import { Formatter } from '@stamhoofd/utility';
@@ -516,7 +516,26 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
             deactivatedRegistrationGroupIds.push(existingRegistration.groupId);
         }
 
-        async function createBalanceItem({ registration, skipZero, amount, unitPrice, description, type, relations }: { amount?: number; skipZero?: boolean; registration: { id: string; payingOrganizationId: string | null; memberId: string; trialUntil: Date | null }; unitPrice: number; description: string; relations: Map<BalanceItemRelationType, BalanceItemRelation>; type: BalanceItemType }) {
+        // Cache the registration period relation per periodId, so we only load each period once.
+        const periodRelationCache = new Map<string, BalanceItemRelation | null>();
+        async function getPeriodRelation(periodId: string): Promise<BalanceItemRelation | null> {
+            if (periodRelationCache.has(periodId)) {
+                return periodRelationCache.get(periodId)!;
+            }
+
+            const period = await RegistrationPeriod.getByID(periodId);
+            const relation = period
+                ? BalanceItemRelation.create({
+                        id: period.id,
+                        name: new TranslatedString(period.getBaseStructure().name),
+                    })
+                : null;
+
+            periodRelationCache.set(periodId, relation);
+            return relation;
+        }
+
+        async function createBalanceItem({ registration, periodId, skipZero, amount, unitPrice, description, type, relations }: { amount?: number; skipZero?: boolean; registration: { id: string; payingOrganizationId: string | null; memberId: string; trialUntil: Date | null }; periodId: string; unitPrice: number; description: string; relations: Map<BalanceItemRelationType, BalanceItemRelation>; type: BalanceItemType }) {
             // NOTE: We also need to save zero-price balance items because for online payments, we need to know which registrations to activate after payment
             if (skipZero === true) {
                 if (unitPrice === 0 || amount === 0) {
@@ -524,6 +543,12 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
                 }
             }
 
+            // Add the registration period (working year) relation so it is visible in the item description.
+            const periodRelation = await getPeriodRelation(periodId);
+            if (periodRelation) {
+                relations.set(BalanceItemRelationType.RegistrationPeriod, periodRelation);
+            }
+
             // Create balance item
             const balanceItem = new BalanceItem();
             balanceItem.registrationId = registration.id;
@@ -608,6 +633,7 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
             // Base price
             await createBalanceItem({
                 registration,
+                periodId: item.group.periodId,
                 unitPrice: item.groupPrice.price.forMember(item.member),
                 type: BalanceItemType.Registration,
                 skipZero: false, // Always create at least one balance item for each registration - even when the price is zero
@@ -621,6 +647,7 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
             for (const option of item.options) {
                 await createBalanceItem({
                     registration,
+                    periodId: item.group.periodId,
                     amount: option.amount,
                     unitPrice: option.option.price.forMember(item.member),
                     skipZero: true, // Do not create for zero option prices
@@ -654,6 +681,7 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
                     // Base price
                     await createBalanceItem({
                         registration,
+                        periodId: item.group.periodId,
                         unitPrice: -discountValue,
                         type: BalanceItemType.RegistrationBundleDiscount,
                         description: discount.name,
@@ -722,6 +750,7 @@ export class RegisterMembersEndpoint extends Endpoint<Params, Query, Body, Respo
 
                 await createBalanceItem({
                     registration: registration.registration,
+                    periodId: registration.group.periodId,
                     unitPrice: -difference,
                     type: BalanceItemType.RegistrationBundleDiscount,
                     description: discount.name,

package/src/endpoints/organization/dashboard/stripe/GetStripePayoutsExportStatusEndpoint.ts

@@ -0,0 +1,32 @@
+import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
+import { Endpoint, Response } from '@simonbackx/simple-endpoints';
+
+import { PayoutExportStatus, StripePayoutsExportEndpoint } from './StripePayoutsExportEndpoint.js';
+
+type Params = Record<string, never>;
+type Body = undefined;
+type Query = undefined;
+type ResponseBody = PayoutExportStatus[];
+
+export class GetStripePayoutsExportStatusEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'GET') {
+            return [false];
+        }
+
+        const params = Endpoint.parseParameters(request.url, '/stripe/payouts/status', {});
+
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+
+    async handle(_: DecodedRequest<Params, Query, Body>) {
+        await StripePayoutsExportEndpoint.authenticate();
+
+        return new Response(StripePayoutsExportEndpoint.queue.map((item) => {
+            return PayoutExportStatus.create(item);
+        }));
+    }
+}

package/src/endpoints/organization/dashboard/stripe/StripePayoutsExportEndpoint.test.ts

@@ -0,0 +1,103 @@
+import { Request } from '@simonbackx/simple-endpoints';
+import { EmailMocker } from '@stamhoofd/email';
+import type { Organization, Token, User } from '@stamhoofd/models';
+import { OrganizationFactory, UserFactory } from '@stamhoofd/models';
+import { Token as TokenModel } from '@stamhoofd/models';
+import { QueueHandler } from '@stamhoofd/queues';
+import { Company } from '@stamhoofd/structures';
+import { STExpect } from '@stamhoofd/test-utils';
+import nock from 'nock';
+
+import { resetNock } from '../../../../../tests/helpers/resetNock.js';
+import { testServer } from '../../../../../tests/helpers/TestServer.js';
+import { initMembershipOrganization } from '../../../../../tests/init/initMembershipOrganization.js';
+import { initPlatformAdmin } from '../../../../../tests/init/initPlatformAdmin.js';
+import { GetStripePayoutsExportStatusEndpoint } from './GetStripePayoutsExportStatusEndpoint.js';
+import { StripePayoutsExportEndpoint } from './StripePayoutsExportEndpoint.js';
+
+describe('Endpoint.StripePayoutsExport', () => {
+    const endpoint = new StripePayoutsExportEndpoint();
+    const statusEndpoint = new GetStripePayoutsExportStatusEndpoint();
+
+    let membershipOrganization: Organization;
+    let admin: User;
+    let adminToken: Token;
+
+    beforeAll(async () => {
+        membershipOrganization = await initMembershipOrganization();
+        membershipOrganization.meta.companies = [
+            Company.create({
+                name: 'Platform BV',
+                companyNumber: '0700000000',
+                VATNumber: 'BE0700000000',
+            }),
+        ];
+        await membershipOrganization.save();
+
+        ({ admin, adminToken } = await initPlatformAdmin());
+    });
+
+    afterEach(() => {
+        resetNock();
+    });
+
+    const post = async (organization: Organization, token: Token) => {
+        const request = Request.buildJson('POST', '/stripe/payouts', organization.getApiHost(), {
+            start: new Date(2026, 2, 1).getTime(),
+            end: new Date(2026, 3, 1).getTime() - 1000,
+        });
+        request.headers.authorization = 'Bearer ' + token.accessToken;
+        return await testServer.test(endpoint, request);
+    };
+
+    const getStatus = async (organization: Organization, token: Token) => {
+        const request = Request.buildJson('GET', '/stripe/payouts/status', organization.getApiHost());
+        request.headers.authorization = 'Bearer ' + token.accessToken;
+        return await testServer.test(statusEndpoint, request);
+    };
+
+    test('A platform admin can export payout reports for the membership organization', async () => {
+        nock('https://api.stripe.com')
+            .get('/v1/payouts')
+            .query(true)
+            .reply(200, { object: 'list', data: [], has_more: false, url: '/v1/payouts' });
+
+        const response = await post(membershipOrganization, adminToken);
+        expect(response.status).toBe(200);
+
+        // Wait for the scheduled report to complete
+        await QueueHandler.awaitAll();
+
+        const emails = await EmailMocker.transactional.getSucceededEmails();
+        const reportEmail = emails.find(e => e.subject.startsWith('Stripe Uitbetalingen'));
+        expect(reportEmail).toBeDefined();
+        expect(reportEmail!.attachments).toHaveLength(1);
+
+        // The report is sent to the user that requested it
+        expect(reportEmail!.to).toContain(admin.email);
+
+        // The queue is empty again
+        const statusResponse = await getStatus(membershipOrganization, adminToken);
+        expect(statusResponse.body).toEqual([]);
+    });
+
+    test('A user without platform full access cannot export payout reports', async () => {
+        const user = await new UserFactory({ organization: membershipOrganization }).create();
+        const token = await TokenModel.createToken(user);
+
+        await expect(post(membershipOrganization, token)).rejects.toThrow(
+            STExpect.simpleError({ code: 'permission_denied' }),
+        );
+        await expect(getStatus(membershipOrganization, token)).rejects.toThrow(
+            STExpect.simpleError({ code: 'permission_denied' }),
+        );
+    });
+
+    test('Payout reports are not available for other organizations', async () => {
+        const otherOrganization = await new OrganizationFactory({}).create();
+
+        await expect(post(otherOrganization, adminToken)).rejects.toThrow(
+            STExpect.simpleError({ code: 'not_available' }),
+        );
+    });
+});

package/src/endpoints/organization/dashboard/stripe/StripePayoutsExportEndpoint.ts

@@ -0,0 +1,125 @@
+import type { Decoder } from '@simonbackx/simple-encoding';
+import { AutoEncoder, DateDecoder, field, IntegerDecoder } from '@simonbackx/simple-encoding';
+import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
+import { Endpoint, Response } from '@simonbackx/simple-endpoints';
+import { SimpleError } from '@simonbackx/simple-errors';
+import { Platform } from '@stamhoofd/models';
+import { QueueHandler } from '@stamhoofd/queues';
+
+import { Context } from '../../../../helpers/Context.js';
+import { StripePayoutReporter } from '../../../../helpers/StripePayoutReporter.js';
+
+export class PayoutExportStatus extends AutoEncoder {
+    @field({ decoder: DateDecoder })
+    start: Date;
+
+    @field({ decoder: DateDecoder })
+    end: Date;
+
+    @field({ decoder: IntegerDecoder })
+    count = 0;
+}
+
+type Params = Record<string, never>;
+class Body extends AutoEncoder {
+    @field({ decoder: DateDecoder })
+    start: Date;
+
+    @field({ decoder: DateDecoder })
+    end: Date;
+}
+type Query = undefined;
+type ResponseBody = undefined;
+
+/**
+ * Manually build a Stripe payout report for a given period and email it (to check whether
+ * everything we charged via Stripe application fees was invoiced correctly).
+ */
+export class StripePayoutsExportEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    bodyDecoder = Body as Decoder<Body>;
+
+    static queue: PayoutExportStatus[] = [];
+
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'POST') {
+            return [false];
+        }
+
+        const params = Endpoint.parseParameters(request.url, '/stripe/payouts', {});
+
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+
+    static async authenticate() {
+        const organization = await Context.setOrganizationScope();
+        const { user } = await Context.authenticate();
+
+        if (!Context.auth.hasPlatformFullAccess()) {
+            throw Context.auth.error();
+        }
+
+        const platform = await Platform.getShared();
+        if (!platform.membershipOrganizationId || platform.membershipOrganizationId !== organization.id) {
+            throw new SimpleError({
+                code: 'not_available',
+                message: 'Stripe payout exports are only available for the platform membership organization',
+                statusCode: 400,
+            });
+        }
+
+        return { organization, user };
+    }
+
+    async handle(request: DecodedRequest<Params, Query, Body>) {
+        const { organization, user } = await StripePayoutsExportEndpoint.authenticate();
+
+        if (!STAMHOOFD.STRIPE_SECRET_KEY) {
+            throw new SimpleError({
+                code: 'not_configured',
+                message: 'Stripe is not configured',
+                statusCode: 400,
+            });
+        }
+        const secretKey = STAMHOOFD.STRIPE_SECRET_KEY;
+
+        const start = request.body.start;
+        const end = request.body.end;
+
+        const item = PayoutExportStatus.create({
+            start,
+            end,
+            count: 0,
+        });
+        StripePayoutsExportEndpoint.queue.push(item);
+
+        // Schedule
+        QueueHandler.schedule('stripe-payout-export', async () => {
+            try {
+                const reporter = new StripePayoutReporter({
+                    secretKey,
+                    sellingOrganization: organization,
+                });
+                let count = 0;
+                reporter.callback = () => {
+                    count++;
+                    item.count = count;
+                };
+
+                await reporter.build(start, end);
+
+                // Send the report to the user that requested it
+                await reporter.sendEmail({
+                    to: [{ email: user.email, name: user.name }],
+                });
+            } finally {
+                // Remove from queue
+                StripePayoutsExportEndpoint.queue.splice(StripePayoutsExportEndpoint.queue.indexOf(item), 1);
+            }
+        }).catch(console.error);
+
+        return new Response(undefined);
+    }
+}

package/src/helpers/MembershipCharger.ts

@@ -1,5 +1,5 @@
 import { SimpleError } from '@simonbackx/simple-errors';
-import { BalanceItem, Member, MemberPlatformMembership, Platform } from '@stamhoofd/models';
+import { BalanceItem, Member, MemberPlatformMembership, Platform, RegistrationPeriod } from '@stamhoofd/models';
 import { SQL, SQLOrderBy, SQLWhereSign } from '@stamhoofd/sql';
 import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, TranslatedString } from '@stamhoofd/structures';
 import { Formatter } from '@stamhoofd/utility';
@@ -25,6 +25,25 @@ export const MembershipCharger = {
             return platform.config.membershipTypes.find(t => t.id === id);
         }
 
+        // Cache the registration period relation per periodId, so we only load each period once.
+        const periodRelationCache = new Map<string, BalanceItemRelation | null>();
+        async function getPeriodRelation(periodId: string): Promise<BalanceItemRelation | null> {
+            if (periodRelationCache.has(periodId)) {
+                return periodRelationCache.get(periodId)!;
+            }
+
+            const period = await RegistrationPeriod.getByID(periodId);
+            const relation = period
+                ? BalanceItemRelation.create({
+                        id: period.id,
+                        name: new TranslatedString(period.getBaseStructure().name),
+                    })
+                : null;
+
+            periodRelationCache.set(periodId, relation);
+            return relation;
+        }
+
         let createdCount = 0;
         let createdPrice = 0;
         const chunkSize = 100;
@@ -114,6 +133,12 @@ export const MembershipCharger = {
                     ],
                 ]);
 
+                // Add the registration period (working year) relation so it is visible in the item description.
+                const periodRelation = await getPeriodRelation(membership.periodId);
+                if (periodRelation) {
+                    balanceItem.relations.set(BalanceItemRelationType.RegistrationPeriod, periodRelation);
+                }
+
                 balanceItem.type = BalanceItemType.PlatformMembership;
                 balanceItem.organizationId = chargeVia;
                 balanceItem.payingOrganizationId = membership.organizationId;

package/src/helpers/RegistrationPeriodRelationBackfiller.test.ts

@@ -0,0 +1,111 @@
+import type { RegistrationPeriod } from '@stamhoofd/models';
+import { BalanceItem, BalanceItemFactory, GroupFactory, MemberFactory, MemberPlatformMembership, OrganizationFactory, OrganizationRegistrationPeriodFactory, RegistrationFactory, RegistrationPeriodFactory } from '@stamhoofd/models';
+import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, TranslatedString } from '@stamhoofd/structures';
+import { TestUtils } from '@stamhoofd/test-utils';
+import { v4 as uuidv4 } from 'uuid';
+import { backfillRegistrationPeriodRelations } from './RegistrationPeriodRelationBackfiller.js';
+
+describe('helper.RegistrationPeriodRelationBackfiller', () => {
+    let period: RegistrationPeriod;
+
+    beforeAll(async () => {
+        period = await new RegistrationPeriodFactory({
+            startDate: new Date(2024, 0, 1),
+            endDate: new Date(2025, 11, 31),
+        }).create();
+
+        // A deterministic name so we can assert on it.
+        period.customName = 'Werkjaar 2024-2025';
+        await period.save();
+    });
+
+    beforeEach(() => {
+        TestUtils.setEnvironment('userMode', 'platform');
+    });
+
+    it('fills the registration period relation for registration balance items', async () => {
+        const organization = await new OrganizationFactory({ period }).create();
+        await new OrganizationRegistrationPeriodFactory({ organization, period }).create();
+
+        const member = await new MemberFactory({ organization }).create();
+        const group = await new GroupFactory({ organization, period }).create();
+        const registration = await new RegistrationFactory({ member, group }).create();
+
+        const balanceItem = await new BalanceItemFactory({
+            organizationId: organization.id,
+            memberId: member.id,
+            registrationId: registration.id,
+            type: BalanceItemType.Registration,
+            amount: 1,
+            unitPrice: 25_00,
+        }).create();
+
+        expect(balanceItem.relations.has(BalanceItemRelationType.RegistrationPeriod)).toBe(false);
+
+        await backfillRegistrationPeriodRelations();
+
+        const updated = await BalanceItem.getByID(balanceItem.id);
+        expect(updated?.relations.get(BalanceItemRelationType.RegistrationPeriod)).toMatchObject({ id: period.id });
+        expect(updated?.relations.get(BalanceItemRelationType.RegistrationPeriod)?.name.toString()).toBe('Werkjaar 2024-2025');
+    });
+
+    it('fills the registration period relation for platform membership balance items', async () => {
+        const organization = await new OrganizationFactory({ period }).create();
+        const member = await new MemberFactory({ organization }).create();
+
+        const balanceItem = await new BalanceItemFactory({
+            organizationId: organization.id,
+            memberId: member.id,
+            type: BalanceItemType.PlatformMembership,
+            amount: 1,
+            unitPrice: 15_00,
+        }).create();
+
+        const membership = new MemberPlatformMembership();
+        membership.memberId = member.id;
+        membership.membershipTypeId = uuidv4();
+        membership.organizationId = organization.id;
+        membership.periodId = period.id;
+        membership.startDate = new Date(2024, 0, 1);
+        membership.endDate = new Date(2025, 11, 31);
+        membership.balanceItemId = balanceItem.id;
+        await membership.save();
+
+        await backfillRegistrationPeriodRelations();
+
+        const updated = await BalanceItem.getByID(balanceItem.id);
+        expect(updated?.relations.get(BalanceItemRelationType.RegistrationPeriod)).toMatchObject({ id: period.id });
+        expect(updated?.relations.get(BalanceItemRelationType.RegistrationPeriod)?.name.toString()).toBe('Werkjaar 2024-2025');
+    });
+
+    it('does not overwrite an existing registration period relation', async () => {
+        const organization = await new OrganizationFactory({ period }).create();
+        await new OrganizationRegistrationPeriodFactory({ organization, period }).create();
+
+        const member = await new MemberFactory({ organization }).create();
+        const group = await new GroupFactory({ organization, period }).create();
+        const registration = await new RegistrationFactory({ member, group }).create();
+
+        const existingRelations = new Map([
+            [
+                BalanceItemRelationType.RegistrationPeriod,
+                BalanceItemRelation.create({ id: period.id, name: new TranslatedString('Custom period name') }),
+            ],
+        ]);
+
+        const balanceItem = await new BalanceItemFactory({
+            organizationId: organization.id,
+            memberId: member.id,
+            registrationId: registration.id,
+            type: BalanceItemType.Registration,
+            amount: 1,
+            unitPrice: 25_00,
+            relations: existingRelations,
+        }).create();
+
+        await backfillRegistrationPeriodRelations();
+
+        const updated = await BalanceItem.getByID(balanceItem.id);
+        expect(updated?.relations.get(BalanceItemRelationType.RegistrationPeriod)?.name.toString()).toBe('Custom period name');
+    });
+});

package/src/helpers/RegistrationPeriodRelationBackfiller.ts

@@ -0,0 +1,125 @@
+import { BalanceItem, MemberPlatformMembership, Registration, RegistrationPeriod } from '@stamhoofd/models';
+import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, TranslatedString } from '@stamhoofd/structures';
+import { Formatter } from '@stamhoofd/utility';
+import { SeedTools } from './SeedTools.js';
+
+/**
+ * Backfills the `RegistrationPeriod` relation on existing balance items.
+ *
+ * The relation contains the name of the registration period (working year) connected to a registration
+ * (or its options / bundle discount) and to a platform membership. It was added after these balance items
+ * were created, so we reconstruct it from the linked registration or membership.
+ *
+ * Only balance items that don't have the relation yet are touched, so the migration is idempotent and never
+ * overwrites relations that were already set by the current flows.
+ */
+
+/**
+ * Loads the registration period relation once per periodId.
+ */
+class PeriodRelationCache {
+    private cache = new Map<string, BalanceItemRelation | null>();
+
+    async get(periodId: string): Promise<BalanceItemRelation | null> {
+        if (this.cache.has(periodId)) {
+            return this.cache.get(periodId)!;
+        }
+
+        const period = await RegistrationPeriod.getByID(periodId);
+        const relation = period
+            ? BalanceItemRelation.create({
+                    id: period.id,
+                    name: new TranslatedString(period.getBaseStructure().name),
+                })
+            : null;
+
+        this.cache.set(periodId, relation);
+        return relation;
+    }
+}
+
+async function backfillRegistrationBalanceItems(cache: PeriodRelationCache): Promise<number> {
+    let updated = 0;
+
+    await SeedTools.loopBatched({
+        batchSize: 100,
+        query: BalanceItem.select().whereNot('registrationId', null),
+        batchAction: async (items: BalanceItem[]) => {
+            const registrationIds = Formatter.uniqueArray(items.map(i => i.registrationId!).filter(id => !!id));
+            const registrations = await Registration.getByIDs(...registrationIds);
+            const registrationMap = new Map(registrations.map(r => [r.id, r]));
+
+            for (const item of items) {
+                // Never overwrite a relation that is already set.
+                if (item.relations.has(BalanceItemRelationType.RegistrationPeriod)) {
+                    continue;
+                }
+
+                const registration = registrationMap.get(item.registrationId!);
+                if (!registration) {
+                    continue;
+                }
+
+                const relation = await cache.get(registration.periodId);
+                if (!relation) {
+                    continue;
+                }
+
+                item.relations.set(BalanceItemRelationType.RegistrationPeriod, relation);
+                await item.save();
+                updated += 1;
+            }
+        },
+    });
+
+    return updated;
+}
+
+async function backfillPlatformMembershipBalanceItems(cache: PeriodRelationCache): Promise<number> {
+    let updated = 0;
+
+    await SeedTools.loopBatched({
+        batchSize: 100,
+        query: BalanceItem.select().where('type', BalanceItemType.PlatformMembership),
+        batchAction: async (items: BalanceItem[]) => {
+            const balanceItemIds = items.map(i => i.id);
+            const memberships = await MemberPlatformMembership.select()
+                .where('balanceItemId', balanceItemIds)
+                .limit(balanceItemIds.length)
+                .fetch();
+            const membershipByBalanceItemId = new Map(memberships.filter(m => m.balanceItemId).map(m => [m.balanceItemId!, m]));
+
+            for (const item of items) {
+                if (item.relations.has(BalanceItemRelationType.RegistrationPeriod)) {
+                    continue;
+                }
+
+                const membership = membershipByBalanceItemId.get(item.id);
+                if (!membership) {
+                    continue;
+                }
+
+                const relation = await cache.get(membership.periodId);
+                if (!relation) {
+                    continue;
+                }
+
+                item.relations.set(BalanceItemRelationType.RegistrationPeriod, relation);
+                await item.save();
+                updated += 1;
+            }
+        },
+    });
+
+    return updated;
+}
+
+export async function backfillRegistrationPeriodRelations(): Promise<{ registrations: number; memberships: number }> {
+    const cache = new PeriodRelationCache();
+    const registrations = await backfillRegistrationBalanceItems(cache);
+    const memberships = await backfillPlatformMembershipBalanceItems(cache);
+
+    console.log(`[RegistrationPeriodRelationBackfiller] Updated ${registrations} registration balance items and ${memberships} platform membership balance items`);
+
+    return { registrations, memberships };
+}