API Reference
Subscriptions API
Verified beta subscription settings and current subscription state behavior for checkout, customer access, plugin licensing, delivery, and Stripe webhooks.
SoundSync
Developer settings endpoints
These are developer-authenticated and mutate product subscription configuration.
GET
/api/developer/products/:productId/subscription-settings
Return beta product subscription settings for a developer-owned product.
- Auth
- Developer dashboard/user JWT.
- Scope
- Developer-owned product settings.
- Request fields
- Developer JWT
- productId path parameter
- Returns
- settings { enabled, billingInterval, trialDays, failedPaymentGraceDays, cancellationBehavior }, betaEnabled.
- Side effects
- Ensures a product_subscription_settings row exists for the product.
PUT
/api/developer/products/:productId/subscription-settings
Update beta product subscription settings.
- Auth
- Developer dashboard/user JWT.
- Scope
- Developer-owned product settings.
- Request fields
- Developer JWT
- enabled
- billingInterval monthly|yearly
- trialDays 0|7|14|30
- failedPaymentGraceDays 0|3|7
- cancellationBehavior access_until_period_end|lock_immediately
- Returns
- Updated settings and betaEnabled.
- Side effects
- Writes subscription settings and records product setup activity.
- Notes
- This is a mutation and is not used during read-only screenshot capture.
SoundSync
Verified subscription states
Only states normalized by the implementation are listed.
| State | Billing meaning | Customer access | Plugin access | Download access | Offline grace |
|---|---|---|---|---|---|
| incomplete | Stripe subscription setup has not completed. | No durable customer access until checkout completes. | Plugin should remain locked. | No protected downloads. | No offline grace. |
| trialing | Trial period is active. | Customer access is allowed while trial is valid. | Plugin access follows entitlement/subscription payload. | Downloads are allowed while entitlement remains active. | Grace follows product validation rules. |
| active | Recurring billing is active. | Customer access is allowed. | Plugin access is allowed unless another denial applies. | Downloads are allowed. | Grace follows product validation rules. |
| past_due | Payment failed but collection/grace may still be active. | Access depends on failedPaymentGraceDays and platform subscription payload. | Plugin may return subscription_payment_required after grace. | Downloads may be blocked when entitlement is inactive. | Do not invent extra grace locally. |
| unpaid | Stripe marks subscription unpaid. | Access should be denied. | Plugin locks with subscription_inactive/payment-required behavior. | Downloads blocked when entitlement inactive. | No offline grace for explicit denial. |
| canceled | Subscription was canceled/deleted. | Access follows cancellationBehavior and period-end timestamps. | Plugin locks when subscription entitlement is inactive. | Downloads blocked when entitlement inactive. | No offline grace for explicit denial. |
Stripe dependency
Initial checkout uses Stripe subscription checkout. Lifecycle updates are handled from checkout.session.completed, customer.subscription.updated, and customer.subscription.deleted where the event is recognized as product subscription checkout.