Critical Documentation Gap: Custom Subscriptions Broadcast Behavior Not Documented

[ojozef]

Description

The Amplify Gen2 documentation fails to clearly explain that custom subscriptions (.for(mutation)) broadcast to ALL subscribers, unlike model-based subscriptions which filter by owner. This leads to unexpected costs and architectural issues in production applications.

Expected Behavior
Documentation should clearly distinguish between:

• Model subscriptions - server-side filtered, targeted delivery
• Custom subscriptions - broadcast to all subscribers, client-side filtering required

Actual Behavior

• No clear documentation about broadcast behavior of custom subscriptions
• Developers assume custom subscriptions work like model subscriptions
• Cost implications are not mentioned

Impact
Financial: For 1M active users, a single custom subscription event costs:

• Model subscription: ~$0.002 (1 user receives notification)
• Custom subscription: ~$2.00 (1M users receive notification)

Difference: 1000x cost increase

Architectural: Developers unknowingly create inefficient real-time systems.

Categories

• Analytics
• API (REST)
• API (GraphQL)
• Auth
• Authenticator
• DataStore
• Notifications (Push)
• Storage

Steps to Reproduce

• Create custom subscription with .for(mutation) (https://docs.amplify.aws/react/build-a-backend/data/custom-business-logic/)
• Have multiple users subscribe
• Trigger mutation
• Observe all subscribers receive notification (not just relevant users)

Screenshots

No response

Platforms

• iOS
• Android
• Web
• macOS
• Windows
• Linux

Flutter Version

3.32.2

Amplify Flutter Version

2.6.3

Deployment Method

Amplify Gen 2

Schema

[tyllark]

Hello @ojozef, thanks for taking the time to open this issue. We are investigating and will get back to you here when we have an update.