Prevent duplicate subscriptions with subscription buckets

Problem Statement

Pelcro currently allows a user to have multiple active subscriptions of the same type or within the same logical grouping, especially when subscriptions are created via the API.

This creates problems for:

• In-app purchases (Apple App Store / Google Play), where platforms enforce one active subscription per group

• Web subscriptions, where users can accidentally subscribe twice

• Client apps, which must implement complex and fragile idempotency logic

Apple and Google solve this with subscription groups that behave like radio buttons: one active subscription per group, while still allowing upgrades and downgrades.

Pelcro lacks a native equivalent.

User Story

As a Pelcro merchant or integrator
I want to define subscription groups that enforce one active subscription per user per group
So that duplicate subscriptions are prevented and upgrades/downgrades are handled cleanly across web, API, and mobile platforms.

Proposed Behavior (High Level)

• Plans may optionally belong to a Subscription Group

• A user may have only one active subscription per group

• Creating a subscription in the same group will:

  • Trigger an upgrade/downgrade flow or

  • Be rejected with a clear, deterministic API error (behavior TBD)

Multiple Groups Are Supported

• A platform may define multiple independent subscription groups

• A user may have one active subscription per group

• Example:

  • Group A: Content Access

  • Group B: Add-on / Premium Tier
    → One active subscription per group is valid and supported

Definition of Done (DoD)

• Subscription Groups can be created and managed

• Plans can be assigned to a group

• Pelcro enforces one active subscription per user per group

• Upgrade/downgrade within a group is supported

• Duplicate subscriptions in the same group are prevented at the platform level

• API behavior is documented and test-covered

• Backward compatible for plans not assigned to a group

Impacted Components

• API – enforcement and upgrade/downgrade logic

• Admin UI – group and plan management

• JS-SDK – subscription creation flows

• Integrations – Apple App Store, Google Play Store, Web Checkout

Business Impact

• Simplifies in-app purchase integrations

• Prevents double billing and duplicate entitlements

• Improves upgrade/downgrade UX

• Aligns Pelcro with Apple / Google subscription models