7010/Support more flexible subscription intervals #7069

Yopi · 2025-09-30T06:49:33Z

📋 Summary

Related Issue: Fixes #7010

This PR adds a recurring_interval_count in addition to the recurring_interval on the product and subscription models. Additionally it makes the cycle calculations for billing take the recurring_interval_count in consideration.

🎯 What

Backend:

Add the necessary properties to the Product and Subscription models
Create the database migration to add those fields and migrate existing Products and Subscriptions
Expose and handle those properties correctly in the Product, Subscription and Checkout API
Handle the configuration correctly when handling a cycle.

Frontend

Adapt the Product creation/update form to configure the recurring interval
- [?] Nice to have: show quick and common configurations by default like 1 month or 1 year[ ]
Display the interval nicely across the dashboard (Product details, Subscription details…)
Display the interval nicely in the Customer Portal
Display the interval nicely in the Checkout form

🤔 Why

To allow for more flexibility in billing intervals.

🔧 How

🧪 Testing

I have tested these changes locally
All existing tests pass (uv run task test for backend, pnpm test for frontend)
I have added new tests for new functionality
I have run linting and type checking (uv run task lint && uv run task lint_types for backend)

Test Instructions

🖼️ Screenshots/Recordings

📝 Additional Notes

✅ Pre-submission Checklist

[WIP] My code follows the project's style guidelines
I have performed a self-review of my code
I have commented my code where necessary
[X I have made corresponding changes to the documentation
My changes generate no new warnings
I have updated the relevant tests
All tests pass locally
AI/LLM Policy: If I used AI assistance, I have tested and executed the code locally (not just "vibe-coded")

vercel · 2025-09-30T06:49:38Z

@Yopi is attempting to deploy a commit to the polar-sh Team on Vercel.

A member of the Team first needs to authorize it.

Yopi · 2025-10-01T17:47:58Z

clients/apps/web/src/components/Products/CreateProductPage.tsx

          {},
        ),
-      })
+      } as schemas['ProductCreate'])


Not super impressed with having to do this, but Typescript couldn't figure the type out without it when I added the recurring_interval_count number / null.

Yeah, it usually gets a bit tricky with those forms. We can live with it IMO :)

Yopi · 2025-10-01T17:50:49Z

clients/apps/web/src/components/Products/ProductForm/ProductPricingSection.tsx

+                required: 'This field is required when billing cycle is set',
+                min: { value: 1, message: 'Interval count must be at least 1' },
+                max: {
+                  value: 999,


This probably doesn't really make sense, but I'm also not sure what would make sense here out of a product perspective.

Had the same debate with the trial configuration, and ended up also limiting to 1000. A bit arbitrary, but at least make sure we don't blow up datetimes.

Yopi · 2025-10-01T17:51:26Z

clients/apps/web/src/components/Products/ProductForm/ProductPricingSection.tsx

+                      Set how often customers are billed (e.g., &quot;every 2
+                      months&quot;)


I wanted to have an example here since it might not be intuitive, but we might also want to update the example based on the recurring_interval for it to be a bit more dynamic.

Yeah, I guess we'll have quite a lot of back and forth on this UX. Will do fine for now.

Yopi · 2025-10-01T17:52:13Z

clients/apps/web/src/components/Shared/AmountLabel.tsx

    switch (interval) {
      case 'day':
-        return ' / dy'
+        return ` /${prefix} dy`


It looks fine to me, but the text becomes a bit longer and I am guessing the intention was for it to be short given that it's being shortened (wk, etc).

Looks great 👍

Yopi · 2025-10-01T17:53:49Z

server/polar/subscription/schemas.py

+    recurring_interval_count: int | None = Field(
+        description=(
+            "Number of interval units of the subscription."
+            "If this is set to 1 the charge will happen every interval (e.g. every month),"


Same here, due to the possibility of it not being intuitive I wanted to give a clearer example.

Looks great 👍

frankie567

Thank you @Yopi, very great and polished work 🙏

I suggested a few nitpicks; if you have time to address them, would be great 🙂

➕ if you can pass linters: uv run task lint && uv run task lint_types

frankie567 · 2025-10-02T09:22:12Z

server/polar/models/product.py

        index=True,
        default=None,
    )
+    recurring_interval_count: Mapped[int | None] = mapped_column(


I think this should be made non-nullable, especially since we take care to migrate existing data.

That was my initial thought as well, but when recurring_interval is null I made this null as well. Otherwise we would need to give it a value. Perhaps setting it to 0 would make sense though?

frankie567 · 2025-10-02T09:22:48Z

server/polar/models/subscription.py

    recurring_interval: Mapped[SubscriptionRecurringInterval] = mapped_column(
        StringEnum(SubscriptionRecurringInterval), nullable=False, index=True
    )
+    recurring_interval_count: Mapped[int | None] = mapped_column(


See comment above about non-nullable

frankie567 · 2025-10-02T09:24:07Z

server/polar/subscription/schemas.py

+    recurring_interval_count: int | None = Field(
+        description=(
+            "Number of interval units of the subscription."
+            "If this is set to 1 the charge will happen every interval (e.g. every month),"


Looks great 👍

frankie567 · 2025-10-02T09:25:02Z

server/polar/subscription/service.py

        if product.is_legacy_recurring_price:
            prices = [checkout.product_price]
            recurring_interval = prices[0].recurring_interval
+            recurring_interval_count = 1


Good catch 😄

frankie567 · 2025-10-02T09:28:07Z

clients/apps/web/src/components/Products/CreateProductPage.tsx

          {},
        ),
-      })
+      } as schemas['ProductCreate'])


Yeah, it usually gets a bit tricky with those forms. We can live with it IMO :)

frankie567 · 2025-10-02T09:29:32Z

clients/apps/web/src/components/Products/ProductForm/ProductPricingSection.tsx

+                required: 'This field is required when billing cycle is set',
+                min: { value: 1, message: 'Interval count must be at least 1' },
+                max: {
+                  value: 999,


Had the same debate with the trial configuration, and ended up also limiting to 1000. A bit arbitrary, but at least make sure we don't blow up datetimes.

server/polar/product/schemas.py

frankie567 · 2025-10-02T09:30:13Z

server/polar/product/schemas.py

    )
+    recurring_interval_count: int | None = Field(
+        default=None,
+        ge=1,


We should also probably add the upper limit validation here.

frankie567 · 2025-10-02T09:31:17Z

clients/apps/web/src/components/Products/ProductForm/ProductPricingSection.tsx

+                      Set how often customers are billed (e.g., &quot;every 2
+                      months&quot;)


Yeah, I guess we'll have quite a lot of back and forth on this UX. Will do fine for now.

frankie567 · 2025-10-02T09:32:03Z

clients/apps/web/src/components/Shared/AmountLabel.tsx

    switch (interval) {
      case 'day':
-        return ' / dy'
+        return ` /${prefix} dy`


Looks great 👍

vercel · 2025-10-02T09:34:30Z

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
polar	Ignored	Preview		Oct 2, 2025 9:34am
polar-sandbox	Ignored	Preview		Oct 2, 2025 9:34am

Yopi · 2025-10-02T10:03:09Z

Thank you @Yopi, very great and polished work 🙏

I suggested a few nitpicks; if you have time to address them, would be great 🙂

➕ if you can pass linters: uv run task lint && uv run task lint_types

Sorry, I thought I had ran through the linter, but seems not. All should be good now.

I pushed the changes you requested (made the recurring_interval_count not nullable and defaulted to 0 when we don't have a recurring_interval)

This adds a recurring_interval_count column for the product and subscription models, allowing for a more granular control of the cycle for the subscription. We default the cycle to 1, which will conform the current data to every x (every month, every year, etc). We allow this to be nullable similar to the recurring_interval field.

…e it in the cycle calculation

Yopi · 2025-10-23T09:06:42Z

Superseded by #7410 and #7431

Yopi force-pushed the 7010-flexible-subscription-intervals branch 3 times, most recently from 709f890 to 851e515 Compare October 1, 2025 17:47

Yopi commented Oct 1, 2025

View reviewed changes

Yopi marked this pull request as ready for review October 1, 2025 17:56

frankie567 requested changes Oct 2, 2025

View reviewed changes

Yopi force-pushed the 7010-flexible-subscription-intervals branch from 851e515 to 12a9543 Compare October 2, 2025 10:00

Yopi and others added 12 commits October 22, 2025 10:35

server/subscription: Expose recurring_interval_count on API and handl…

626f94d

…e it in the cycle calculation

server/product: Expose recurring_interval_count on API

dd981e3

clients/web: Add billing frequency options

8e58d0c

web: add recurring_interval_count to preview objects

90ca1f3

web: Enforce that the types for ProductCreate are correct

9122c50

web: Add recuring interval count to AmountLabel

1695e32

product: Allow day and week intervals for recurring

29d8f32

endpoints: Add tests for day, week and recurring interval count

0a22c87

fixup! server/product+subscriptions: Add recurring_interval_count

f130e5c

fix(checkout): Add formatter for non-1 recurring interval count

438e7de

subscriptions: Add recurring interval count

ce4a919

Yopi force-pushed the 7010-flexible-subscription-intervals branch from 12a9543 to ce4a919 Compare October 22, 2025 10:02

This was referenced Oct 22, 2025

Flexible subscription intervals (pt1) #7410

Merged

Flexible subscription intervals (pt2 / checkout) #7431

Merged

Yopi closed this Oct 23, 2025

7010/Support more flexible subscription intervals #7069

7010/Support more flexible subscription intervals #7069

Uh oh!

Conversation

Yopi commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Summary

🎯 What

🤔 Why

🔧 How

🧪 Testing

Test Instructions

🖼️ Screenshots/Recordings

📝 Additional Notes

✅ Pre-submission Checklist

Uh oh!

vercel bot commented Sep 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

frankie567 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vercel bot commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Yopi commented Oct 2, 2025

Uh oh!

Yopi commented Oct 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Yopi commented Sep 30, 2025 •

edited

Loading

frankie567 left a comment •

edited

Loading

vercel bot commented Oct 2, 2025 •

edited

Loading