Guide

Subscription Bundle API

Versioned bundle definitions, signed-in checkout, customer plan changes, billing setup, and recurring reporting.

Start with getting started Explore API docs

SoundSync

Customer checkout and billing

Current route and service contracts. Examples below are illustrative; live provider outcomes and client-host testing are separate checks.

GET /api/subscriptions/bundles/:bundleId

Read a published bundle and its current version.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: bundleId path
Returns: { bundle } with interval, amounts, trial/grace settings, membershipMode, fulfillmentMode, versionId, and products.
Side effects: Read-only unless the operation explicitly records referral activity.
Notes: Public read; unpublished or unavailable bundles cannot be used for checkout.

POST /api/subscriptions/bundles/checkout

Create a Stripe checkout session for the signed-in buyer.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: bundleId
Optional promoCode and taxQuoteId
Idempotency-Key header or idempotencyKey body
Returns: 201: provider, checkoutSessionId, url, customerId, bundle, and conflicts.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: The server supplies buyer identity and required environment. Keep-products ownership requires eligible live payment evidence; a session URL does not grant ownership.

POST /api/subscriptions/bundles/change-preview

Inspect a proposed plan change and its timing.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: currentSubscriptionId
targetBundleId
Optional effectiveMode
Returns: 201: preview, proposed timing, amounts, and conflict context.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: The current subscription must belong to the signed-in buyer. Read the preview before confirmation.

POST /api/subscriptions/bundles/change-confirm

Confirm a still-valid plan preview.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: previewId
idempotencyKey
Returns: 201 for a new confirmation or 200 for a duplicate.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: Do not reuse a stale preview or create a second payment after an uncertain response.

POST /api/subscriptions/bundles/cancel

Schedule the supported cancellation at period end.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: bundleSubscriptionId
Returns: Current cancellation/subscription result.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: Cancellation is not a refund. Previously earned keep-products ownership remains unless its source payment is reversed.

POST /api/subscriptions/bundles/reactivate

Resume an eligible plan before the cancellation takes effect.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: bundleSubscriptionId
Returns: Current subscription/reactivation result.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: Eligibility is checked against the current plan and provider state.

POST /api/subscriptions/bundles/cancel-scheduled-change

Remove a pending supported plan change.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: bundleSubscriptionId
Returns: Current scheduled-change result.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: This cancels a plan change, not the subscription itself.

POST /api/subscriptions/bundles/billing-portal

Create an authorized customer billing-portal session.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: bundleSubscriptionId or standaloneSubscriptionId
Returns: Provider billing-portal session result.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: Keep session URLs private. The billing portal does not itself validate audio access.

POST /api/subscriptions/bundles/manual-billing-setup

Begin billing setup for an eligible manually granted subscription.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: kind: bundle or standalone
subscriptionId
Returns: 201: billing setup-session result.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: A manual access grant does not mean the customer already has a recurring provider payment arrangement.

POST /api/subscriptions/bundles/manual-billing-preview

Preview billing after the customer completes setup.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: kind
subscriptionId
sessionId
Returns: Current billing quote and setup result.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: Customer ownership and provider setup completion are verified.

POST /api/subscriptions/bundles/manual-billing-confirm

Confirm the reviewed manual-grant billing amount.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: kind
subscriptionId
sessionId
expectedTotalCents
Returns: Billing confirmation result.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: A changed quote is rejected rather than silently charging a different amount.

GET /api/subscriptions/bundles/customer/subscriptions

List the signed-in customer's subscriptions for one developer.

Auth: Public bundle detail is unauthenticated. All customer mutations and customer subscription lists require the signed-in customer session.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: developerId query
Returns: { subscriptions } or an empty list.
Side effects: Read-only unless the operation explicitly records referral activity.
Notes: The server resolves the customer from the signed-in user; do not supply another customer identity.

SoundSync

Developer bundle management

Current route and service contracts. Examples below are illustrative; live provider outcomes and client-host testing are separate checks.

GET /api/developer/subscription-bundles

List bundle definitions in the effective developer workspace.

Auth: Developer Bearer JWT in the effective workspace, products.view, mutation permissions, and the stated product scope.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: Optional status query
Returns: Scoped bundle list.
Side effects: Read-only unless the operation explicitly records referral activity.
Notes: products.view and all-products scope.

GET /api/developer/subscription-bundles/:bundleId

Read an owned bundle definition and versions.

Auth: Developer Bearer JWT in the effective workspace, products.view, mutation permissions, and the stated product scope.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: bundleId path
Returns: { bundle }.
Side effects: Read-only unless the operation explicitly records referral activity.
Notes: products.view and all-products scope; another developer's definition is not exposed.

POST /api/developer/subscription-bundles

Create a bundle definition and version.

Auth: Developer Bearer JWT in the effective workspace, products.view, mutation permissions, and the stated product scope.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: name and optional description/slug
productIds for selected_products
membershipMode: selected_products or all_products
fulfillmentMode: access or keep_products
billingInterval, basePriceStrategy and corresponding price/discount values
Optional trialDays, failedPaymentGraceDays, cancellationBehavior, status, and environment
Returns: 201: created bundle/version result.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: products.edit; selected products must be in scope, and all_products requires all-products scope. Keep discounted paid amounts at least $9.99 before tax.

PUT /api/developer/subscription-bundles/:bundleId

Update an owned bundle through the versioned definition workflow.

Auth: Developer Bearer JWT in the effective workspace, products.view, mutation permissions, and the stated product scope.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: bundleId path
name and optional description/slug
productIds for selected_products
membershipMode: selected_products or all_products
fulfillmentMode: access or keep_products
billingInterval, basePriceStrategy and corresponding price/discount values
Optional trialDays, failedPaymentGraceDays, cancellationBehavior, status, and environment
Returns: Updated bundle/version result.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: products.edit and relevant product scope. Do not assume changing the catalog rewrites every prior paid-invoice ownership snapshot.

PATCH /api/developer/subscription-bundles/:bundleId

Change bundle publication/status.

Auth: Developer Bearer JWT in the effective workspace, products.view, mutation permissions, and the stated product scope.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Request fields: bundleId path
status
Returns: Current bundle/status result.
Side effects: Performs the described operation; review confirmation and retry requirements.
Notes: products.edit and all-products scope.

GET /api/developer/subscription-bundles/reporting/summary

Read recurring bundle reporting totals.

Auth: Developer Bearer JWT in the effective workspace, products.view, mutation permissions, and the stated product scope.
Scope: Authenticated account, workspace, relationship, and product ownership checks apply.
Returns: { summary } with active_subscriptions, recurring_amount_cents, past_due_subscriptions.
Side effects: Read-only unless the operation explicitly records referral activity.
Notes: products.view and all-products scope. Recurring amount is not a confirmed payout or proof every invoice was paid.

SoundSync

Illustrative customer cancellation

curl -X POST "https://www.soundsync.dev/api/subscriptions/bundles/cancel" \
  -H "Authorization: Bearer CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"bundleSubscriptionId":123}'

Access, ownership, and payment are separate states

An access plan grants recurring use while its entitlement is valid. A keep_products plan records product ownership from eligible verified paid invoices and their catalog snapshots. An unpaid trial or a manually supplied active state is not permanent paid ownership. Canceling future renewal does not remove ownership earned from an unreversed prior payment.

The standard refund policy covers the initial subscription payment within 14 days, not renewals. Original-payment reversals reconcile corresponding financial shares and product access. Independent purchases and unrelated ownership grants must not be erased.

Errors and environment checks

Errors use code and message with field or conflicts where supplied. Relevant rejection codes include subscription_bundle_already_active, subscription_bundle_change_recommended, subscription_bundle_payment_required, subscription_bundle_environment_mismatch, and subscription_bundle_live_required. Inspect the operation result before retrying. These are source-backed contracts; the example is illustrative rather than a captured provider transcript.