Guide
Commerce Overview
SoundSync commerce systems from checkout through payment provider completion, orders, ledger, entitlements, library access, billing, settlement, tax, marketplace, and promotions.
SoundSync
Checkout to access
The documented path is implementation-backed and intentionally avoids internal owner-only controls.
-
Product or cart
Public storefront, marketplace, embed, or direct client sends productId/items to /api/checkout/product.
-
Checkout session
platform resolves product owner, server price, promo code, tax quote, Stripe mode, safe return URLs, and checkout session record.
-
Payment provider
Stripe Checkout handles payment collection; free claims bypass Stripe only after server-side zero-total resolution.
-
Webhook completion
Verified Stripe webhook processes checkout.session.completed with provider-event/idempotency protection.
-
Order and ledger
Order service writes order, order items, sale ledger, optional journal/settlement allocation, and marketplace shares.
-
Entitlement and library
Order service grants entitlements; customer library and delivery endpoints expose access.
-
Download and activation
Downloads use entitlement-gated delivery; plugin activation/validation uses product credential and entitlement/license state.
SoundSync
System boundaries
Use this map to keep public, developer, partner, and owner-only operations separate.
| Area | Public/developer surface | Boundary |
|---|---|---|
| Checkout | /api/checkout/product and /api/checkout/quote | Public buyer call, server-authoritative money. |
| Orders | Developer analytics/reporting and partner external order lookup | Internal order tables are not exposed as broad public admin APIs. |
| Refunds/disputes | Developer docs explain effects; partner has scoped external-order refund route | Owner/provider controls remain internal. |
| Billing/settlement | /api/developer/billing/* and /api/developer/settlements/* | Developer-visible balances/statements only; owner emergency controls are not public docs. |
| Tax/MoR | Quote and jurisdiction endpoints plus docs | Documentation describes platform behavior, not tax/legal advice. |
