Workflow and language updates

In-app purchases data and workflows

This section explains the data sources, operators, database tables, and workflow actions that become available when you enable in-app purchases (IAP). These tools let you implement subscription logic using the same patterns you already use elsewhere in Bubble.

Subscription purchases (system table)

Bubble automatically creates and manages a Subscription Purchases system table. This table serves as the source of truth for a user’s subscription state.

What this table represents

Each record represents a single subscription entitlement for a user. Records are created and updated based on billing notifications sent by Apple and Google. You can think of this table as a read-only system log that reflects the current state of a user’s subscription.

Key characteristics

• Records are created and updated automatically when Apple or Google sends billing events, such as purchases, renewals, cancellations, or expirations

• Records can’t be created, modified, or deleted manually

• Updates occur near real time based on server-side notifications

Common fields you can rely on

While exact field names may evolve, you can generally expect access to:

• User: the Bubble user who owns the subscription

• Billing variant: the Bubble subscription object tied to the entitlement

• Status: values such as PAID, ENDING, or EXPIRED

• Store: Apple App Store or Google Play

• Environment: sandbox or live

• Renewal and expiration dates

Use this table primarily for visibility and debugging. For gating features and building app logic, prefer the operators and data sources described below rather than querying this table directly.

New data sources

Bubble exposes high-level data sources that surface a user’s subscription state safely and consistently.

Current user’s subscription

Returns the active subscription for the current user, if one exists.

Common use cases include:

• Showing a Manage subscription screen

• Displaying plan details such as tier name, billing frequency, or renewal date

• Conditionally showing upgrade or downgrade options

If the user doesn’t have an active subscription, this data source returns empty.

New operators

Operators are the primary way to control access to features, content, and UI based on subscription state.

User is subscribed to subscription group

Returns yes or no depending on whether the user has any active subscription within a given subscription group.

Common use cases:

• Locking an entire feature area behind a paid plan

• Checking whether the user has any paid access

User is subscribed to subscription tier

Returns yes or no if the user is subscribed to a specific tier, such as Pro.

Common use cases:

• Enabling premium-only features

• Showing tier-specific UI or limits

User is at least subscribed to subscription tier

Returns yes or no if the user is subscribed to at least a given tier, based on the order defined in the subscription group.

Common use cases:

• Enabling features available to multiple plans without checking each tier individually

User is subscribed to billing variant

Returns yes or no if the user is subscribed to a specific billing variant, such as Pro – Annual.

Common use cases:

• Showing renewal-specific messaging

• Differentiating monthly versus annual subscribers

In most cases, it’s best to gate access at the subscription group or tier level. Billing-variant checks are better suited for messaging or analytics rather than core access control.

Workflow actions

Bubble adds native workflow actions for initiating and managing subscriptions. These actions automatically invoke Apple or Google’s in-app purchase flows.

Initiate subscription purchase

Starts a native in-app purchase flow for a selected billing variant.

Key behaviors:

• Opens the Apple or Google payment sheet

• Handles receipt validation automatically

• Updates the Subscription Purchases table when the purchase completes

You can select a billing variant directly or pass one dynamically, such as from a repeating group.

A typical flow looks like this:

• The user taps an Upgrade or Subscribe button

• The workflow runs Initiate subscription purchase

• Bubble hands off to Apple or Google

• The subscription state updates automatically

Manage subscription

Redirects the user to the platform-native subscription management screen.

Use this action to allow users to:

• Cancel a subscription

• Change billing frequency

• Upgrade or downgrade within a subscription group

Apple and Google control the management UI. Bubble provides the entry point, not the management controls themselves.

Backend workflow events (server notifications)

Bubble exposes backend workflow events that fire when Apple or Google sends billing notifications.

In-app purchase event

This event triggers whenever Bubble receives a server-side billing update, such as when a subscription is created, renewed, canceled, or expires.

Event types you may receive

When the backend workflow runs, Bubble provides a normalized event type that represents the subscription lifecycle change. These events are abstracted across Apple and Google so you can write platform-agnostic logic.

Event type	When it fires	Typical meaning
created	A subscription purchase succeeds	The user now has an active subscription
expired	A canceled subscription ends	The user no longer has an active subscription
sub_renewed	A subscription renews successfully	A recurring billing cycle completed
sub_resumed	A paused subscription becomes active again (Google only)	Billing was resumed
sub_auto_renew_enabled	Auto-renew is turned back on	The subscription will continue renewing
sub_auto_renew_disabled	Auto-renew is turned off	The subscription will end after the current cycle
sub_entered_grace	A subscription enters a grace period	Payment failed but access may be temporarily granted
sub_on_hold	A subscription is placed on hold	Payment issue requiring user action
sub_paused	A subscription is paused (Google only)	Billing temporarily stopped
sub_voided	A charge is refunded	A billing period was refunded

Some platform updates are intentionally filtered out and won’t trigger an event, including initial pending payments, internal product migrations, or platform-specific transitions that don’t represent a meaningful state change for app logic. In these cases, the subscription record may still update internally, but no backend event fires.

What Bubble handles automatically

Bubble takes care of:

• Validating receipts

• Updating the Subscription Purchases table

• Maintaining the user’s current subscription state

What you can customize

Backend workflows let you add your own business logic, such as:

• Sending an email when a subscription starts

• Notifying your team when a high-tier plan is purchased

• Logging analytics events

• Syncing subscription state to external systems

Backend workflows are optional. Subscriptions work without them, and they’re intended for advanced or custom behavior.

Recommended implementation pattern

• Gate access using operators at the group or tier level

• Initiate purchases using workflow actions

• Use backend workflows only for side effects like emails, analytics, or syncing

• Treat the Subscription Purchases table as read-only system data

Following this pattern keeps your app aligned with Apple and Google requirements while keeping your Bubble logic simple and maintainable.