API Reference
Subscriptions API
Verified beta subscription settings and current subscription state behavior for checkout, customer access, plugin licensing, delivery, and Stripe webhooks.
Product credentials
Activation request
Entitlement check
Device registration
Periodic validation
Deactivation when needed
SoundSync
Developer settings endpoints
These are developer-authenticated and mutate product subscription configuration.
/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.
/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.
API reference
Endpoint groups are organized by authentication model, product scope, request shape, response shape, errors, idempotency, and integration surface.
Subscriptions API
/docs/api/subscriptions
Beta product subscription settings and subscription state behavior.